How to Use the Income-Investment Skill to Distinguish Sustainable Dividend Stocks From Yield Traps

The income-investment skill applies a rigorous nine-step workflow with hard gating rules to classify dividend stocks as CORE INCOME, OPPORTUNISTIC INCOME, or YIELD TRAP based on cash-flow coverage, debt health, and business durability.

The income-investment skill in the xbtlin/ai-berkshire repository provides a systematic framework for analyzing dividend sustainability. Unlike simple yield screening, this skill evaluates cash-flow coverage, debt profiles, and business quality to distinguish durable income generators from high-yield traps. It operates through a structured research workflow defined in skills/income-investment.md that enforces data-quality checks and quantitative gates before issuing a final verdict.

How the Income-Investment Skill Works

The skill executes a nine-step analytical pipeline that transforms a ticker symbol into a categorical investment verdict. Each step is designed to surface evidence of sustainability or trap characteristics.

Step 1: Parse Request and Establish Data Quality

The skill reads the command line (e.g., /income-investment "AAPL" …) and extracts the company ticker, analysis mode, investment role, and optional portfolio parameters. It immediately rates the available evidence as Grade A, B, or C. If fundamentals are missing or unreliable, the workflow stops at the INSUFFICIENT DATA gate defined in skills/income-investment.md.

Step 2: Distribution Analysis

The skill gathers dividend frequency, historical payments, CAGR, and ex-dividend dates for a minimum five-year lookback period. This establishes the baseline continuity of the income stream.

Step 3: Cash-Flow Trace

This step examines the actual sources of dividend funding. The analysis calculates net-income payout ratios, free-cash-flow coverage, debt-service requirements, capital-expenditure needs, and buyback competition. Calculations rely on arithmetic functions in tools/financial_rigor.py.

Step 4: Durability Test

The skill evaluates business moat strength, cyclicality exposure, capital-allocation quality by management, and downside-case cash-flow resilience. This qualitative assessment determines whether the distribution can survive adverse conditions.

Step 5: Valuation and Income Calculation

Current yield, intrinsic-value ranges, and net-income-after-tax figures are computed to contextualize the income stream’s price relative to its risk-adjusted value.

Step 6: Portfolio Fit (Optional)

When provided with a portfolio_file parameter, the skill checks weight limits, sector concentration, and diversification constraints to prevent portfolio-level risk accumulation.

Step 7: Three-Scenario Modeling

The skill constructs base, adverse, and severe stress-test scenarios that explicitly model dividend-cut risk under varying economic conditions.

Step 8: Classification, Gates, and Verdict

A qualitative scorecard assigns ratings to dimensions like business quality and cash-flow visibility. However, these scores are subordinate to the hard gates described below.

Hard Gates That Automatically Flag Yield Traps

Regardless of headline yield or qualitative scorecard results, the skill applies five non-negotiable rejection criteria (referenced at lines 132-138 in skills/income-investment.md). If any gate triggers, the verdict is forced to REJECT / YIELD TRAP or REDUCE for existing positions:

• Recurring uncovered distribution — Dividends consistently exceeding free cash flow or net income
• Critical debt or refinancing risk — Near-term maturity walls or covenant breach potential that threatens liquidity
• Structural business deterioration — Irreversible revenue decline, technological obsolescence, or regulatory impairment
• Insufficient fundamental data — Inability to verify financials or ambiguous reporting standards (Grade C evidence)
• Material governance or integrity concerns — Accounting irregularities, related-party conflicts, or management credibility issues

These gates ensure that a high yield alone cannot mask fundamental weakness.

Classification Categories Explained

After passing all gates and scoring, the skill assigns one of five categorical verdicts:

Category	Definition
CORE INCOME	Strong business quality, cash-flow visibility, dividend coverage ≥70%, solid balance sheet, and consistent dividend growth. Suitable for long-term portfolio anchors.
OPPORTUNISTIC INCOME	Adequate quality with attractive yield-on-cost, but elevated uncertainty (modest coverage, sector-specific risks, or cyclical exposure). Appropriate for tactical, monitored positions.
YIELD TRAP	Failed one or more hard gates. Characterized by weak coverage, critical refinancing risk, recurring uncovered distributions, or structural decline. Avoid adding; reduce existing exposure.
WATCHLIST / HOLD – DO NOT ADD	Generally sound quality, but portfolio concentration limits or sector-risk thresholds prevent new allocation.
INSUFFICIENT DATA	Inadequate primary source material to assess sustainability. Analysis halts until better data is available.

Running the Skill: Command Syntax and Examples

Invoke the skill via slash command with explicit parameters to control the analysis scope:

/income-investment "T" mode=new role=core-income portfolio_file=my_portfolio.yaml horizon=5y

Parameter breakdown:

• "T" — Target ticker symbol
• mode=new — Generates a fresh analysis report rather than updating an existing file
• role=core-income — Biases scoring toward durability and consistency requirements
• portfolio_file=my_portfolio.yaml — Enables the portfolio-fit step for concentration checking
• horizon=5y — Requests five years of distribution history for the CAGR calculation

The skill outputs a markdown report saved to reports/T-income-investment-YYYYMMDD.md containing the verdict and detailed scorecard:

## Verdict and category

**CORE INCOME**

## Scorecard

| Dimension            | Rating   | Evidence |
|----------------------|----------|----------|
| Business quality     | Strong   | Wide moat, pricing power |
| Cash-flow visibility | Adequate | Recurring subscription revenue |
| Dividend coverage    | Strong   | 85% FCF payout |

If a hard gate triggers, the verdict section displays:

## Verdict and category

**REJECT / YIELD TRAP**

Key Source Files and Validation Tools

The income-investment skill relies on several interconnected components within the xbtlin/ai-berkshire codebase:

• skills/income-investment.md — Master specification document containing the full workflow, command syntax syntax, gating logic, and classification rubric.

• codex-skills/income-investment/SKILL.md — Codex-compatible wrapper that exposes the workflow to AI assistant slash commands while maintaining identical logic.

• tools/financial_rigor.py — Provides exact arithmetic implementations for payout ratios, yield-on-cost calculations, and scenario modeling mathematics used in steps 3, 5, and 7.

• tools/report_audit.py — Post-generation validation utility that cross-checks the markdown report outputs against source data to ensure "verified fact" standards are met.

• skills/financial-data.md — Auxiliary workflow invoked to cross-validate key financial figures against primary sources before inclusion in the analysis.

Summary

• The income-investment skill offers a systematic, code-based alternative to discretionary dividend screening through its nine-step workflow in skills/income-investment.md.

• Hard gates (coverage, debt, business health, data quality, governance) override all qualitative scores to prevent yield-trap allocation.

• Valid classifications are CORE INCOME, OPPORTUNISTIC INCOME, YIELD TRAP, WATCHLIST, and INSUFFICIENT DATA.

• Use the command /income-investment "TICKER" mode=new role=core-income to generate auditable reports saved to the reports/ directory.

• Supporting tools like tools/financial_rigor.py and tools/report_audit.py ensure mathematical accuracy and data integrity.

Frequently Asked Questions

What makes the income-investment skill different from standard dividend screeners?

Standard screeners filter by static metrics like current yield or P/E ratios. The income-investment skill conducts a dynamic cash-flow trace and applies hard quantitative gates that cannot be overridden by qualitative optimism. It also integrates portfolio-fit constraints and stress-test scenarios that screeners typically ignore.

How does the skill define a yield trap specifically?

A yield trap is any stock that triggers at least one of the five hard gates: recurring uncovered distributions, critical debt/refinancing risk, structural business deterioration, insufficient data, or material governance concerns. This classification persists even if the dividend appears covered by accounting earnings or the yield appears statistically attractive.

Can I run the income-investment skill without a portfolio file?

Yes. The portfolio_file parameter is optional. When omitted, the skill skips the Portfolio Fit step and proceeds directly to the three-scenario modeling and classification steps. However, including the file enables concentration-risk checking that may downgrade a stock to WATCHLIST status despite strong fundamentals.

What happens if the evidence quality is rated Grade C?

Grade C evidence triggers the INSUFFICIENT DATA gate, causing the workflow to halt before calculating coverage ratios or durability scores. The skill outputs a verdict of INSUFFICIENT DATA and refuses to classify the stock as CORE INCOME, OPPORTUNISTIC INCOME, or YIELD TRAP until better primary sources become available.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}