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

> Master the income-investment skill to identify truly sustainable dividend stocks and avoid yield traps. Our nine-step workflow provides clear distinctions for CORE INCOME, OPPORTUNISTIC INCOME, and YIELD TRAP classifications. L...

- Repository: [Xbt Lin/ai-berkshire](https://github.com/xbtlin/ai-berkshire)
- Tags: how-to-guide
- Published: 2026-07-28

---

**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`](https://github.com/xbtlin/ai-berkshire/blob/main/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`](https://github.com/xbtlin/ai-berkshire/blob/main/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`](https://github.com/xbtlin/ai-berkshire/blob/main/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`](https://github.com/xbtlin/ai-berkshire/blob/main/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:

```text
/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`](https://github.com/xbtlin/ai-berkshire/blob/main/reports/T-income-investment-YYYYMMDD.md) containing the verdict and detailed scorecard:

```markdown

## 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:

```markdown

## 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`](https://github.com/xbtlin/ai-berkshire/blob/main/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`](https://github.com/xbtlin/ai-berkshire/blob/main/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`](https://github.com/xbtlin/ai-berkshire/blob/main/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`](https://github.com/xbtlin/ai-berkshire/blob/main/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`](https://github.com/xbtlin/ai-berkshire/blob/main/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`](https://github.com/xbtlin/ai-berkshire/blob/main/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`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py) and [`tools/report_audit.py`](https://github.com/xbtlin/ai-berkshire/blob/main/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.