@v587d/capital-generation 2.7.12 → 2.8.0

package/selected-skills/InvestSkill/plugins/us-stock-analysis/skills/position-ladder/references/12-phase-6-the-thesis.md

@@ -0,0 +1,105 @@
+# 7. Phase 6 — The Thesis-Break Gate
+
+Part 3 of 4 for `position-ladder` — 7. Phase 6 — The Thesis-Break Gate; 8. Scenario Presets; 9. Worked Example
+See `SKILL.md` for what to read and when; this part is procedure, not routing.
+
+## 7. Phase 6 — The Thesis-Break Gate
+
+A ladder is only legitimate on a name still worth owning. Without this gate, disciplined averaging down is a machine for concentrating capital into deteriorating businesses.
+
+**Hard stop — abandon the ladder and consider exiting, do not add — if any of these fire:**
+
+- The original investment thesis has been **falsified**, not merely delayed: structural margin compression, permanent demand loss, a broken product cycle, or the moat breached.
+- Accounting or governance red flags surface (run `bear-case`; a restatement, auditor change, or aggressive revenue recognition ends the ladder).
+- Leverage deterioration: covenant risk, a distressed refinancing, or dilutive emergency financing.
+- The decline is **fundamental, not technical** — consensus estimates are being cut as fast as the price is falling, so the stock is not getting cheaper.
+- The position has already breached the portfolio concentration cap.
+
+**Do-not-ladder list** — asset types where this framework should refuse to produce a plan and say why:
+
+- **Leveraged and inverse ETFs** — daily rebalancing makes them path-dependent with structural decay; averaging down compounds the decay.
+- **Binary-event names** — single-drug biotechs, litigation-outcome stocks, pending all-cash acquisitions. There is no mean to revert to; the distribution is bimodal.
+- **Anything where the bear case is solvency**, not valuation.
+
+**Regime fit check** — the strategy needs oscillation:
+
+| Signal | Favorable (ladder works) | Unfavorable (ladder misfires) |
+|--------|-------------------------|-------------------------------|
+| ADX(14) | < 25 — no dominant trend | > 30 — strong trend; ladder underfills or catches a falling knife |
+| Price vs. MA200 | Oscillating around it | Extended far above (underfill) or in confirmed breakdown below |
+| ATR as % of price | 1.5–5% — enough movement to fill rungs | < 1% — rungs never fill; > 8% — spacing must widen materially |
+| Recent behavior | Range-bound, repeated tests of support | One-directional, gap-driven |
+
+**Ladder Suitability Score (0–10)** — the skill's headline number:
+
+| Component | Points | What earns full marks |
+|-----------|--------|----------------------|
+| Thesis integrity | 0–3 | Would you buy this fresh today, at this price, knowing nothing of your entry? |
+| Regime fit | 0–2 | Range-bound, mean-reverting, oscillating around a level |
+| Volatility adequacy | 0–2 | ATR wide enough that rungs realistically fill inside the time budget |
+| Position headroom | 0–2 | Full ceiling still fits inside the portfolio concentration cap |
+| Account / tax fit | 0–1 | Tax-advantaged account, or trim levels sit in gain territory |
+
+| Score | Reading |
+|-------|---------|
+| 8.0–10.0 | Ladder is appropriate — execute the plan as modeled |
+| 6.0–7.9 | Workable with a reduced ceiling and wider rungs |
+| 4.0–5.9 | Marginal — prefer a single sized entry over a ladder |
+| 0.0–3.9 | Do not ladder — the thesis, regime, or concentration test failed |
+
+---
+
+## 8. Scenario Presets
+
+Match the preset to the situation, state which was applied, and show the parameters used.
+
+| Preset | Floor / Ceiling | Rung spacing | Sizing | Thesis gate | Notes |
+|--------|----------------|--------------|--------|-------------|-------|
+| **Core compounder** | 60% / 100% | 3–4% or 1× ATR | Equal dollars | Full fundamental gate | Trim only above average cost; long holds favor tax-efficient trims |
+| **Broad-index ETF autopilot** | 50% / 100% | 4–5% or 1× ATR | Equal dollars | None — no company thesis to break | Cleanest use case; regime and cap checks still apply |
+| **High-beta single stock** | 40% / 100% | 8–12% or 1.5× ATR | Pyramid | Strict + hard stop | Smaller ceiling %, wider rungs, mandatory `bear-case` |
+| **Starter + ladder (anti-underfill)** | 40% at market, ladder the rest | 1× ATR | Equal dollars | Full gate | For names that rarely pull back |
+| **Underwater rescue** | Current holding / hard cap | Support-based | Equal dollars | **Mandatory re-underwrite** | Only proceed if the fresh-money test passes; otherwise this is an exit plan, not a ladder |
+
+---
+
+## 9. Worked Example
+
+Position: 20 shares bought at $128. Price now $122. Target band: floor 60 shares, ceiling 100. Equal shares, $3 rungs, taxable account, specific-lot ID.
+
+**Ladder**
+
+| Rung | Price | Shares | Cost | Status |
+|------|-------|--------|------|--------|
+| 1 | $128 | 20 | $2,560 | filled (the original entry) |
+| 2 | $125 | 20 | $2,500 | fills now — above market |
+| 3 | $122 | 20 | $2,440 | fills now — at market |
+| 4 | $119 | 20 | $2,380 | pending |
+| 5 | $116 | 20 | $2,320 | pending |
+
+Full fill: 100 shares, **$12,200** capital, blended average **$122.00**. Drawdown to full fill is **−4.9%** from today's $122 (116 ÷ 122 − 1) — that is the further decline the plan is signing up to sit through, and $4,700 of the $12,200 (rungs 4–5) is still uncommitted. Equal-*dollar* sizing of the same $12,200 would instead yield ~100.1 shares at **$121.85** — mechanically lower, always.
+
+**Trim to floor** — price recovers: sell the $128 lot at $125, then the $125 lot at $128.
+
+- Cash back: (20 × $125) + (20 × $128) = **$5,060**
+- Realized: −$60 on the first lot, +$60 on the second = **$0 net**
+- Remaining: 60 shares at $122 / $119 / $116 → average **$119.00**
+- ⚠️ The $125 sale realized a **$60 loss**. Any repurchase within 30 days is a **wash sale** — the loss is disallowed and added to the replacement shares' basis.
+
+**Re-add to ceiling** — price falls back; buy 20 at $117 and 20 at $115.
+
+- 100 shares, total cash out **$11,780**, average **$117.80** (down from $122.00)
+
+**Reality check at three prices**
+
+| Price path | Buy-and-hold 100 @ $122 | Ladder + cycle |
+|-----------|------------------------|----------------|
+| Back to $122 | $0 | **+$420** — same 100 shares, $4.20 lower basis |
+| Rallies to $140 (trimmed, never re-added) | +$1,800 | **+$1,260** — $540 worse; 40 shares were sold into the rally |
+| Stalls at $115 | −$700 | −$280 on 100 shares at $117.80 |
+
+The middle row is the honest cost of the strategy: **the lower average cost was purchased with forgone upside.** The first row is the edge. Which row you get is decided by the tape, not by the discipline.
+
+---
+
+

package/selected-skills/InvestSkill/plugins/us-stock-analysis/skills/position-ladder/references/13-input-formats.md

@@ -0,0 +1,105 @@
+# 10. Input Formats
+
+Part 4 of 4 for `position-ladder` — 10. Input Formats; 11. Output Format; Notes; Signal Output; Thesis Invalidation
+See `SKILL.md` for what to read and when; this part is procedure, not routing.
+
+## 10. Input Formats
+
+### Format 1: Manage an existing position
+```text
+User: /position-ladder AVGO — I hold 20 shares at $128, now $122. Target 60–100 shares.
+
+Claude builds the ladder, the trim/re-add cycle, and the total-return comparison.
+```
+
+### Format 2: Plan a new position from scratch
+```text
+User: /position-ladder MSFT — new position, max 5% of a $200k portfolio, ETF-style autopilot.
+
+Claude derives the ceiling from the concentration cap and lays out the rungs.
+```
+
+### Format 3: Pasted holdings, multiple positions
+```text
+User: /position-ladder — here are my holdings: [paste]. Which of these should I be laddering?
+
+Claude scores each position's Ladder Suitability and produces a plan only for those that pass the gate.
+```
+
+---
+
+## 11. Output Format
+
+1. **Assumptions Stated** — every input used, every default applied, and what was assumed because it was not supplied. First section, always.
+2. **Position Snapshot** — current shares, average cost, market price, unrealized P&L, weight in portfolio.
+3. **Position Bounds** — floor, ceiling, and which of the three caps was binding.
+4. **Entry Ladder Table** — rungs, sizes, capital at full fill, blended average, drawdown to full fill.
+5. **Trim / Re-Add Cycle Table** — one complete cycle with running average cost and realized P&L.
+6. **Lot Accounting & Tax Notes** — lot method assumed, wash-sale flags with dates, holding-period effects.
+7. **Reality Check** — total return vs. buy-and-hold across all three price paths, in dollars.
+8. **Thesis-Break Gate** — the gate checklist, regime table, and the conditions that end the plan.
+9. **Ladder Suitability Score** — 0–10 with the component breakdown.
+10. **Investment Signal Block**.
+
+Round share counts to whole shares (or state that fractional shares are assumed) and round rung prices to levels that can actually be entered as resting orders.
+
+---
+
+## Notes
+
+- **Complements, does not replace**: run `stock-eval` or `fundamental-analysis` first to establish the thesis, `technical-analysis` for the support levels that make the best rungs, `bear-case` for the gate in Phase 6, and `portfolio-review` for the concentration cap that sets the ceiling.
+- **The strategy is regime-dependent, and the regime is not knowable in advance.** Present it as a bounded, rules-based way to build a position — not as an edge that works everywhere.
+- **Do not raise the ceiling mid-drawdown.** If the analysis concludes the position should be bigger, that is a new decision requiring a fresh thesis, not a ladder adjustment.
+- **Fractional-share brokers change the math** — equal-dollar sizing becomes exact. Say which assumption is in force.
+- Tax treatment is modeled at a high level for **US taxable accounts only**. It is not tax advice; recommend a tax professional for anything material.
+
+## Signal Output
+
+This skill measures **execution suitability, not price direction** — so state the mapping explicitly. The Ladder Suitability Score drives the block: a high score means staged accumulation inside the band is appropriate and the plan should be executed as modeled; a low score means the thesis, regime, or concentration test failed and the correct action is to stop adding. `Action: BUY` here means "continue laddering within the stated cap" — never "buy without limit." `Action: SELL` means the gate failed, not that a short is warranted. Read the direction of the underlying stock from `stock-eval` or `bear-case`, not from this block.
+
+All analysis concludes with this standardized block:
+
+```
+## Thesis Invalidation
+
+After delivering the analysis signal, specify what would reverse it:
+
+**If signal is BULLISH — thesis breaks if:**
+- Price closes below the bottom rung on above-average volume with fundamental deterioration
+- Consensus estimates are cut faster than the price falls (the stock is not getting cheaper)
+- The position reaches its ceiling and the thesis gate no longer passes
+
+**If signal is BEARISH — thesis breaks if:**
+- The falsified thesis element is restored: margins re-expand, demand returns, guidance is raised
+- The regime turns range-bound again (ADX falls below 25) with fundamentals stabilized
+- Valuation resets low enough that a fresh-money buyer would want the full position today
+
+**Re-run this analysis when:**
+- [ ] Next earnings release
+- [ ] Price moves ±15% from current level
+- [ ] Any rung fills or any trim executes
+- [ ] 60 days have elapsed
+- [ ] Material news event (acquisition, leadership change, regulatory decision)
+
+╔══════════════════════════════════════════════╗
+║              INVESTMENT SIGNAL               ║
+╠══════════════════════════════════════════════╣
+║ Signal:      BULLISH / NEUTRAL / BEARISH     ║
+║ Confidence:  HIGH / MEDIUM / LOW             ║
+║ Horizon:     SHORT / MEDIUM / LONG-TERM      ║
+║ Score:       X.X / 10                        ║
+╠══════════════════════════════════════════════╣
+║ Action:      BUY / HOLD / SELL               ║
+║ Conviction:  STRONG / MODERATE / WEAK        ║
+╚══════════════════════════════════════════════╝
+```
+
+Score Guide: 8.0–10.0 Strongly Bullish | 6.0–7.9 Moderately Bullish | 4.0–5.9 Neutral | 2.0–3.9 Moderately Bearish | 0.0–1.9 Strongly Bearish
+Confidence: HIGH (strong data, clear signals) | MEDIUM (mixed signals) | LOW (limited data, conflicting signals)
+Horizon: SHORT-TERM (1 week–3 months) | MEDIUM-TERM (3 months–1 year) | LONG-TERM (1+ years)
+
+**Note:** The Score above is the Ladder Suitability Score, mapped onto the standard scale for cross-skill comparability. It rates *how appropriate staged accumulation is right now* — not how attractive the stock is. Pair it with `/stock-eval` for the directional view.
+
+**Disclaimer:** Educational analysis only. Not financial advice. All price levels and share counts are scenario models under stated assumptions, not trade instructions.
+
+

package/selected-skills/InvestSkill/plugins/us-stock-analysis/skills/risk-stress-test/SKILL.md

@@ -38,256 +38,16 @@ Data & Sources
 
 ---
 
-## Overview
+## Read the Parts
 
-Every other framework in the catalog asks whether a holding is *good*. This one asks the question that decides whether the investor is still around to find out: **how much can the whole book lose, how fast, and can it be sold when it has to be?**
+Everything below the surface of this file lives in `references/`. **whole, with no line window** — quoting a rule or a template out of a slice of one is how a
+file gets reported as read when it was only skimmed. The file names below are the only
+addressing this entry has.
 
-`portfolio-review` covers allocation, drift, and concentration. `economics-analysis` names the regime. Neither converts a list of holdings into a dollar figure for a bad month, replays the portfolio through the crashes that actually happened, or tells the investor how many days it would take to get out. This skill does exactly that and nothing else — it is a **risk report, not a recommendation**. Its verdict is a Risk Budget Score: how far the portfolio's measured risk sits inside (or outside) the drawdown the investor has said they can tolerate.
+- `references/10-overview.md` — Overview; 1. Inputs; 2. Framework
+- `references/11-phase-4-correlation-spike.md` — (continued) 2. Framework; 3. Output Format; Example
+- `references/12-notes.md` — Notes; Thesis Invalidation; Standard Signal Output
 
-**What an assistant can and cannot compute here.** A language model cannot recall a covariance matrix for a specific set of tickers, and must not pretend to. The skill therefore works from **inputs the user pastes or the assistant retrieves** — beta, σ, ADV, weights — and shows every formula it applies, so the arithmetic can be checked line by line. Historical scenario magnitudes are approximate index-level figures and are labelled as such; the reader confirms the ones that matter.
-
-Pairs with: `portfolio-review` (what to hold), `economics-analysis` (which regime the stress is most likely to come from), `position-ladder` (the share-count ceiling this report may lower), `thesis-tracker` (whether a drawdown is a thesis event or just volatility), and `tax-lens` (what a forced de-risking would cost after tax).
-
----
-
-## 1. Inputs
-
-| Input | Required | Default if unstated |
-|-------|----------|---------------------|
-| Holdings with weights (or share counts + prices) | ✅ | — |
-| Per-holding beta (1Y vs. SPY), annualized σ, 30-day ADV | ✅ (paste, retrieve, or state the proxy) | sector-ETF beta / σ, flagged `proxy` |
-| Total portfolio value | ✅ (for dollar figures) | express everything in % |
-| Max-drawdown tolerance (the risk budget) | recommended | propose one from the investor profile: 15 % conservative · 25 % balanced · 40 % aggressive |
-| Horizon | optional | 1 day and 1 month |
-| Benchmark | optional | SPY |
-| Cash / bonds / hedges (puts, inverse ETFs) | optional | assumed zero — say so |
-
-Ask for missing risk inputs rather than inventing them. If the user cannot supply β or σ for a name, use the sector ETF's figures and mark every derived number `(proxy)`.
-
----
-
-## 2. Framework
-
-### Phase 1 — Exposure map (what the book actually is)
-
-Weights first, then what they load onto:
-
-```
-Weight_i        = Value_i / Portfolio Value
-β_p (net beta)  = Σ Weight_i × β_i
-$-beta to SPY   = β_p × Portfolio Value          (dollar move for a 1.00 % SPY move × 100)
-Sector weights  = Σ Weight_i by GICS sector      (flag any sector > 30 %)
-Top-3 weight    = sum of the three largest positions
-```
-
-| Position | Weight | β | σ (ann.) | Sector | Weight × β | ADV ($) |
-|----------|--------|---|----------|--------|------------|---------|
-| … | | | | | | |
-| **Portfolio** | 100 % | **β_p** | *(Phase 4)* | | | |
-
-Say plainly what the book is: "this is a 1.3-beta, 62 %-technology portfolio" is more useful than any statistic that follows.
-
-### Phase 2 — Historical scenario replay
-
-Replay four regimes. **Measure every holding over the scenario's common date window** (the dates in the first column, index peak to index trough) — not each holding's own peak-to-trough, which would combine losses that never happened at the same time. Where a holding existed through the episode, use its actual return over that window; where it did not (or the data is not available), use **β_i × index move** or the sector ETF's return over the same window, and mark the row `proxy`. For the 2025 tariff shock, **write down the window you are using before computing** (the pre-announcement close to the trough) and confirm it with the user — it is recent enough that the dates are not yet a convention. Index magnitudes below are approximate figures for orientation — the user confirms any that drive the conclusion.
-
-| Scenario | Market move (approx.) | Portfolio est. move | Worst position | Note |
-|----------|-----------------------|---------------------|----------------|------|
-| **2008 GFC** (Oct-07 → Mar-09) | SPX ≈ −57 %, ~17 months; financials −80 %+, credit frozen | Σ Weight_i × replay_i | | Long duration of decline matters as much as depth |
-| **March 2020** (Feb-19 → Mar-23) | SPX ≈ −34 % in ~5 weeks; VIX > 80; everything sold at once | | | Speed: correlations went to ~1; liquidity vanished for a fortnight |
-| **2022 rate shock** (Jan → Oct) | SPX ≈ −25 %; Nasdaq-100 ≈ −35 %; long-duration growth −60–80 %; bonds fell *with* stocks | | | Growth / unprofitable tech and 60/40 diversification were the casualties |
-| **2025 tariff shock** (recent regime) | Sharp, policy-driven gap lower and partial recovery; magnitude and dates to be confirmed by the reader | | | Import-cost and China-revenue exposure, not beta, decided the losers |
-
-```
-Portfolio scenario move = Σ Weight_i × Replay_i
-   Replay_i = actual drawdown_i          if the holding traded through the episode
-            = β_i × Index move            otherwise  (mark "proxy")
-Dollar loss             = Portfolio scenario move × Portfolio Value
-```
-
-Report the **worst single scenario in dollars**, and whether it exceeds the risk budget. That comparison is the headline of the report.
-
-### Phase 3 — Parametric VaR and CVaR
-
-```
-σ_p        = portfolio σ from Phase 4 (use the "normal-correlation" figure)
-VaR(α, t)  = z_α × σ_p × √t × Portfolio Value        z_95 = 1.645   z_99 = 2.326
-CVaR(α, t) = (φ(z_α) / (1 − α)) × σ_p × √t × Value   CVaR_95 ≈ 2.063 σ√t · V   CVaR_99 ≈ 2.665 σ√t · V
-t          = 1/252 for 1 day · 21/252 for 1 month   (σ_p is annualized)
-```
-
-| Horizon | VaR 95 % | CVaR 95 % | VaR 99 % | CVaR 99 % |
-|---------|----------|-----------|----------|-----------|
-| 1 day | $ / % | | | |
-| 1 month | $ / % | | | |
-
-**Say what this is and is not.** Parametric VaR assumes normally distributed returns; equity tails are fatter, so realized 99 % losses come more often and run deeper than the table implies. Present VaR as the *floor* of what a bad day looks like, and the scenario replay in Phase 2 as the more honest picture of the tail. If the two disagree by more than 2×, say so and trust the scenario.
-
-### Phase 4 — Correlation spike: the diversification you think you have
-
-Diversification is measured on calm days and disappears on the days it is needed. Compute portfolio σ twice:
-
-```
-σ_p²  = Σ_i Σ_j w_i w_j σ_i σ_j ρ_ij
-
-Normal case : ρ_ij = the pasted / retrieved pairwise correlations
-              (if unavailable: 0.6 within sector · 0.35 across sectors · 0.0 vs. cash — mark "assumed")
-Crisis case : ρ_ij = 0.85 for every equity pair (0.95 within sector); bonds vs. equities 0.3
-              (2022-style: not the −0.3 the 60/40 model assumes)
-
-Diversification benefit = 1 − σ_p / Σ w_i σ_i        (report for both cases)
-```
-
-| | Portfolio σ (ann.) | 1-month VaR 99 % | Diversification benefit |
-|---|---|---|---|
-| Normal correlations | | | |
-| Crisis correlations (ρ → 0.85) | | | |
-
-The gap between the two rows is the amount of "diversification" the portfolio will lose exactly when it is needed. A portfolio whose crisis σ is more than 1.4× its normal σ is diversified in name only.
-
-### Phase 5 — Factor sensitivities
-
-Three exposures that historical beta hides. Score each **Low / Medium / High** with the weight of the portfolio that carries it and the direction of the hit:
-
-| Factor | Who gets hurt | Who benefits | Portfolio exposure | Direction of a +1 σ shock |
-|--------|---------------|--------------|--------------------|---------------------------|
-| **Rates ↑** (10Y +100 bp) | Long-duration growth (high P/S, distant cash flows), REITs, utilities, long bonds | Banks (NIM), insurers, cash | % of book in rate-sensitive names | est. % move |
-| **USD ↑** (DXY +5 %) | Multinationals with > 40 % non-US revenue, commodity producers, EM | Domestic small caps, importers | % of book with heavy foreign revenue | |
-| **Oil ↑** (WTI +25 %) | Airlines, chemicals, consumer discretionary, transports | Energy producers, oil services | % energy vs. % oil-consumers | |
-
-Use each company's segment / geographic disclosure (10-K) for revenue exposure; use the sector as a proxy only when stated.
-
-### Phase 6 — Liquidity: can it actually be sold?
-
-```
-Days to exit_i   = Shares held_i / (0.20 × ADV_i in shares)      (selling no more than 20 % of a day's volume)
-Illiquid weight  = Σ Weight_i where Days to exit_i > 5
-Portfolio exit   = the longest Days-to-exit among positions above 2 % weight
-```
-
-| Position | Shares | ADV (shares) | Days to exit @ 20 % ADV | Flag |
-|----------|--------|--------------|-------------------------|------|
-| … | | | | > 5 days ⚠️ · > 20 days 🔴 |
-
-A position that takes more than a month to exit at 20 % of ADV is a private holding with a ticker. Its drawdown in Phase 2 should be widened by an illiquidity haircut (10–25 %) and said so.
-
-### Phase 7 — Risk Budget Score (0–10)
-
-The headline number. It measures **how far inside the stated drawdown budget the portfolio sits** — not whether the holdings are attractive.
-
-| Component | Weight | 10 looks like | 0 looks like |
-|-----------|--------|---------------|--------------|
-| Worst historical scenario vs. budget | 35 % | Worst replay ≤ 60 % of the budget | Worst replay > 150 % of the budget |
-| 1-month CVaR 99 % vs. budget | 20 % | CVaR ≤ 40 % of the budget | CVaR > budget |
-| Correlation-spike resilience | 15 % | Crisis σ ≤ 1.2× normal σ | Crisis σ > 1.6× normal σ |
-| Concentration (top-3 weight, sector max) | 15 % | Top-3 < 25 %, no sector > 30 % | Top-3 > 50 % or one sector > 50 % |
-| Liquidity | 10 % | Every position exits in ≤ 2 days | > 10 % of the book needs > 20 days |
-| Factor tilt | 5 % | No High exposure on any factor | High on two or more factors, same direction |
-
-```
-Risk Budget Score = Σ component score × weight        (each component scored 0–10, linearly between the anchors)
-```
-
-Map — the same bands as the standard Score Guide: **≥ 6.0 → risk within budget** (signal BULLISH; 8.0+ comfortably so) · **4.0–5.9 → at the edge** (NEUTRAL) · **< 4.0 → over budget** (BEARISH). If no budget was supplied, state the one you assumed and show how the score changes at the other two tolerance levels.
-
----
-
-## 3. Output Format
-
-1. **Data & Sources** header (above) — including the source of every β / σ / ADV and which are proxies
-2. **Headline** — three lines: what the book is (β_p, largest tilts) · worst scenario in dollars vs. the budget · Risk Budget Score
-3. **Exposure map** (Phase 1 table)
-4. **Scenario replay** (Phase 2 table) with proxies marked
-5. **VaR / CVaR** table (Phase 3) with the normal-distribution caveat stated
-6. **Correlation spike** (Phase 4) — normal vs. crisis rows
-7. **Factor sensitivities** (Phase 5)
-8. **Liquidity** (Phase 6) with the longest exit named
-9. **Risk Budget Score** table (Phase 7) and the sensitivity to the budget assumed
-10. **What would bring it inside budget** — the two or three smallest changes (trim X to Y %, add Z % cash, replace A with a lower-β B) with the estimated effect on the worst scenario. Hand the *tax* cost of each to `tax-lens`; hand the *how* to `position-ladder`.
-11. **Thesis Invalidation** and the **Investment Signal block**
-
----
-
-## Example
-
-```
-User: Stress-test this portfolio against 2008 and 2022. $400k total. NVDA 22%, AVGO 15%,
-      MSFT 15%, TSLA 12%, AMZN 10%, XOM 8%, JPM 8%, cash 10%. I can stomach a 25% drawdown.
-      [pastes 1Y betas, σ, and ADV for each]
-
-The assistant maps the book first: net β 1.28, 74% technology / consumer-tech, top-3 weight
-52%, 10% cash. Scenario replay: 2008 ≈ −52% ($−208k, mostly proxy via β — none of the tech
-names' 2008 paths are representative of today's businesses, and it says so); March 2020
-≈ −41% in five weeks; 2022 rate shock ≈ −38% ($−152k) with TSLA (−65%) and NVDA (−50%) as the
-worst positions; 2025 tariff shock flagged as the regime where AVGO / NVDA China exposure, not
-beta, sets the loss — magnitude left for the reader to confirm. Parametric 1-month VaR 99% is
-$−61k, CVaR 99% $−70k — a third of the 2022 replay, so the assistant tells the user to trust the
-replay, not the VaR. Crisis-correlation σ is 1.5× normal σ: the seven names diversify each
-other on quiet days only. Liquidity is fine (every position exits in under a day). Factor tilt:
-High on rates (long-duration growth), Medium on USD, oil roughly neutral (XOM vs. AMZN/TSLA).
-Risk Budget Score 3.4 / 10 — every historical scenario except a mild one breaches the 25%
-budget. Smallest fixes: trim TSLA 12 → 5% and NVDA 22 → 15% into cash (worst-scenario loss
-falls to ≈ −29%), or accept the tail and restate the budget at 40%. Tax cost of the trims →
-tax-lens; how to execute → position-ladder.
-```
-
----
-
-## Notes
-
-- **This is a report, not a trade list.** The Risk Budget Score says whether the risk fits the budget; deciding what to do about it belongs to `portfolio-review`, `position-ladder`, and the investor.
-- **Every number is only as good as the pasted inputs.** State proxies, assumed correlations, and index magnitudes as such. If more than a third of the risk inputs are proxies, the header's Confidence is LOW regardless of source quality.
-- **Scenario dates and magnitudes are approximate** orientation figures for major indices; the user confirms any that decide the verdict, especially the recent 2025 regime.
-- **Options and hedges**: if the user holds puts or inverse products, model them as a negative-β sleeve with a stated hedge ratio, and note that hedges decay and roll — a hedge's protection is for the period it covers, not forever.
-- **Rebalance the budget, not just the book.** A user who cannot stomach the worst historical scenario for their current book has two honest choices: less risk, or a bigger stated budget. Present both.
-- Run `economics-analysis` first when the question is *which* of the four regimes is nearest; run `thesis-tracker --update` after a drawdown to separate a broken thesis from ordinary volatility.
-
-## Thesis Invalidation
-
-After delivering the analysis signal, specify what would reverse it:
-
-**If signal is BULLISH (risk within budget) — the verdict breaks if:**
-- Any position drifts above the concentration anchors in Phase 7 (top-3 > 50 % or one sector > 30 %) through price appreciation alone — the book re-rates itself without a trade
-- Realized 30-day correlations between the top holdings rise above 0.7 in calm markets — the crisis case is becoming the base case
-- `economics-analysis` flags a regime shift toward the scenario that produced this book's worst replay (late-cycle → recession, or a renewed rate-hiking path for a long-duration book)
-- ADV of any position above 5 % weight halves — the liquidity assumption no longer holds
-
-**If signal is BEARISH (over budget) — the verdict breaks if:**
-- The proposed trims / cash raise are executed and the worst-scenario replay falls inside the budget (re-run to confirm the number, not the intention)
-- The user restates the drawdown budget with a written reason (horizon, income, other assets) — the score is relative to the budget, so an honest larger budget changes it
-- A hedge sleeve is added with a stated ratio and roll plan that brings the crisis-correlation σ inside the anchor
-
-**Re-run this analysis when:**
-- [ ] Quarter-end, or any rebalance
-- [ ] Any single position moves ±25 % relative to the portfolio
-- [ ] VIX closes above 30, or the 10-year yield moves ±75 bp in a quarter
-- [ ] A contribution or withdrawal larger than 10 % of portfolio value
-- [ ] The investor's horizon, income needs, or stated drawdown budget change
-
-## Standard Signal Output
-
-This skill measures **whether the portfolio's risk fits the investor's budget, not whether its holdings will rise**, so state the mapping: `Signal: BULLISH` means the measured risk is inside the stated drawdown budget with margin; `NEUTRAL` means it sits at the edge; `BEARISH` means the worst plausible scenario breaches it. `Action: BUY` here means "the current risk level is acceptable to hold" — never "buy more." `Action: SELL` means "reduce risk," not that any holding is a short. Read the direction of the individual holdings from `stock-eval` or `bear-case`, not from this block.
-
-All analysis concludes with this standardized block:
-
-```
-╔══════════════════════════════════════════════╗
-║              INVESTMENT SIGNAL               ║
-╠══════════════════════════════════════════════╣
-║ Signal:      BULLISH / NEUTRAL / BEARISH     ║
-║ Confidence:  HIGH / MEDIUM / LOW             ║
-║ Horizon:     SHORT / MEDIUM / LONG-TERM      ║
-║ Score:       X.X / 10                        ║
-╠══════════════════════════════════════════════╣
-║ Action:      BUY / HOLD / SELL               ║
-║ Conviction:  STRONG / MODERATE / WEAK        ║
-╚══════════════════════════════════════════════╝
-```
-
-Score Guide: 8.0–10.0 Strongly Bullish | 6.0–7.9 Moderately Bullish | 4.0–5.9 Neutral | 2.0–3.9 Moderately Bearish | 0.0–1.9 Strongly Bearish
-Confidence: HIGH (strong data, clear signals) | MEDIUM (mixed signals) | LOW (limited data, conflicting signals)
-Horizon: SHORT-TERM (1 week–3 months) | MEDIUM-TERM (3 months–1 year) | LONG-TERM (1+ years)
-
-**Note:** The Score above is the Risk Budget Score, mapped onto the standard scale for cross-skill comparability. It rates *how far inside the stated drawdown budget the portfolio sits* — not how attractive the holdings are. Confidence is LOW whenever more than a third of the β / σ / ADV inputs are proxies or assumed correlations were used.
-
-**Disclaimer:** Educational analysis only. Not financial advice. VaR, scenario replays, and drawdown estimates are models under stated assumptions; realized losses can and do exceed them.
+Loading this file is not reading the skill: the steps, templates, and thresholds exist only
+in the parts above. Say which parts you opened, name the ones you did not, and never report a
+step or a template you have not read in this session.

package/selected-skills/InvestSkill/plugins/us-stock-analysis/skills/risk-stress-test/references/10-overview.md

@@ -0,0 +1,92 @@
+# Overview
+
+Part 1 of 3 for `risk-stress-test` — Overview; 1. Inputs; 2. Framework
+See `SKILL.md` for what to read and when; this part is procedure, not routing.
+
+## Overview
+
+Every other framework in the catalog asks whether a holding is *good*. This one asks the question that decides whether the investor is still around to find out: **how much can the whole book lose, how fast, and can it be sold when it has to be?**
+
+`portfolio-review` covers allocation, drift, and concentration. `economics-analysis` names the regime. Neither converts a list of holdings into a dollar figure for a bad month, replays the portfolio through the crashes that actually happened, or tells the investor how many days it would take to get out. This skill does exactly that and nothing else — it is a **risk report, not a recommendation**. Its verdict is a Risk Budget Score: how far the portfolio's measured risk sits inside (or outside) the drawdown the investor has said they can tolerate.
+
+**What an assistant can and cannot compute here.** A language model cannot recall a covariance matrix for a specific set of tickers, and must not pretend to. The skill therefore works from **inputs the user pastes or the assistant retrieves** — beta, σ, ADV, weights — and shows every formula it applies, so the arithmetic can be checked line by line. Historical scenario magnitudes are approximate index-level figures and are labelled as such; the reader confirms the ones that matter.
+
+Pairs with: `portfolio-review` (what to hold), `economics-analysis` (which regime the stress is most likely to come from), `position-ladder` (the share-count ceiling this report may lower), `thesis-tracker` (whether a drawdown is a thesis event or just volatility), and `tax-lens` (what a forced de-risking would cost after tax).
+
+---
+
+## 1. Inputs
+
+| Input | Required | Default if unstated |
+|-------|----------|---------------------|
+| Holdings with weights (or share counts + prices) | ✅ | — |
+| Per-holding beta (1Y vs. SPY), annualized σ, 30-day ADV | ✅ (paste, retrieve, or state the proxy) | sector-ETF beta / σ, flagged `proxy` |
+| Total portfolio value | ✅ (for dollar figures) | express everything in % |
+| Max-drawdown tolerance (the risk budget) | recommended | propose one from the investor profile: 15 % conservative · 25 % balanced · 40 % aggressive |
+| Horizon | optional | 1 day and 1 month |
+| Benchmark | optional | SPY |
+| Cash / bonds / hedges (puts, inverse ETFs) | optional | assumed zero — say so |
+
+Ask for missing risk inputs rather than inventing them. If the user cannot supply β or σ for a name, use the sector ETF's figures and mark every derived number `(proxy)`.
+
+---
+
+## 2. Framework
+
+### Phase 1 — Exposure map (what the book actually is)
+
+Weights first, then what they load onto:
+
+```
+Weight_i        = Value_i / Portfolio Value
+β_p (net beta)  = Σ Weight_i × β_i
+$-beta to SPY   = β_p × Portfolio Value          (dollar move for a 1.00 % SPY move × 100)
+Sector weights  = Σ Weight_i by GICS sector      (flag any sector > 30 %)
+Top-3 weight    = sum of the three largest positions
+```
+
+| Position | Weight | β | σ (ann.) | Sector | Weight × β | ADV ($) |
+|----------|--------|---|----------|--------|------------|---------|
+| … | | | | | | |
+| **Portfolio** | 100 % | **β_p** | *(Phase 4)* | | | |
+
+Say plainly what the book is: "this is a 1.3-beta, 62 %-technology portfolio" is more useful than any statistic that follows.
+
+### Phase 2 — Historical scenario replay
+
+Replay four regimes. **Measure every holding over the scenario's common date window** (the dates in the first column, index peak to index trough) — not each holding's own peak-to-trough, which would combine losses that never happened at the same time. Where a holding existed through the episode, use its actual return over that window; where it did not (or the data is not available), use **β_i × index move** or the sector ETF's return over the same window, and mark the row `proxy`. For the 2025 tariff shock, **write down the window you are using before computing** (the pre-announcement close to the trough) and confirm it with the user — it is recent enough that the dates are not yet a convention. Index magnitudes below are approximate figures for orientation — the user confirms any that drive the conclusion.
+
+| Scenario | Market move (approx.) | Portfolio est. move | Worst position | Note |
+|----------|-----------------------|---------------------|----------------|------|
+| **2008 GFC** (Oct-07 → Mar-09) | SPX ≈ −57 %, ~17 months; financials −80 %+, credit frozen | Σ Weight_i × replay_i | | Long duration of decline matters as much as depth |
+| **March 2020** (Feb-19 → Mar-23) | SPX ≈ −34 % in ~5 weeks; VIX > 80; everything sold at once | | | Speed: correlations went to ~1; liquidity vanished for a fortnight |
+| **2022 rate shock** (Jan → Oct) | SPX ≈ −25 %; Nasdaq-100 ≈ −35 %; long-duration growth −60–80 %; bonds fell *with* stocks | | | Growth / unprofitable tech and 60/40 diversification were the casualties |
+| **2025 tariff shock** (recent regime) | Sharp, policy-driven gap lower and partial recovery; magnitude and dates to be confirmed by the reader | | | Import-cost and China-revenue exposure, not beta, decided the losers |
+
+```
+Portfolio scenario move = Σ Weight_i × Replay_i
+   Replay_i = actual drawdown_i          if the holding traded through the episode
+            = β_i × Index move            otherwise  (mark "proxy")
+Dollar loss             = Portfolio scenario move × Portfolio Value
+```
+
+Report the **worst single scenario in dollars**, and whether it exceeds the risk budget. That comparison is the headline of the report.
+
+### Phase 3 — Parametric VaR and CVaR
+
+```
+σ_p        = portfolio σ from Phase 4 (use the "normal-correlation" figure)
+VaR(α, t)  = z_α × σ_p × √t × Portfolio Value        z_95 = 1.645   z_99 = 2.326
+CVaR(α, t) = (φ(z_α) / (1 − α)) × σ_p × √t × Value   CVaR_95 ≈ 2.063 σ√t · V   CVaR_99 ≈ 2.665 σ√t · V
+t          = 1/252 for 1 day · 21/252 for 1 month   (σ_p is annualized)
+```
+
+| Horizon | VaR 95 % | CVaR 95 % | VaR 99 % | CVaR 99 % |
+|---------|----------|-----------|----------|-----------|
+| 1 day | $ / % | | | |
+| 1 month | $ / % | | | |
+
+**Say what this is and is not.** Parametric VaR assumes normally distributed returns; equity tails are fatter, so realized 99 % losses come more often and run deeper than the table implies. Present VaR as the *floor* of what a bad day looks like, and the scenario replay in Phase 2 as the more honest picture of the tail. If the two disagree by more than 2×, say so and trust the scenario.
+
+
+This section is not finished here: `2. Framework` continues in `references/11-phase-4-correlation-spike.md`.