@v587d/capital-generation 2.7.12 → 2.8.0

package/selected-skills/InvestSkill/plugins/us-stock-analysis/skills/portfolio-review/references/11-phase-6-correlation-diversification.md

@@ -0,0 +1,124 @@
+# Phase 6 — Correlation & Diversification Analysis
+
+Part 2 of 4 for `portfolio-review` — Phase 6 — Correlation & Diversification Analysis; Phase 7 — Tax-Loss Harvesting Opportunities; Phase 8 — Factor Exposure Analysis
+See `SKILL.md` for what to read and when; this part is procedure, not routing.
+
+## Phase 6 — Correlation & Diversification Analysis
+
+**Measuring Diversification Benefit**
+
+Portfolio volatility reduction vs. average asset volatility signals diversification quality. If portfolio vol ≈ average position vol, diversification benefit is near zero.
+
+Diversification Ratio = (Weighted average individual vol) / (Portfolio vol)
+- Ratio > 1.5: Good diversification
+- Ratio 1.2–1.5: Moderate
+- Ratio < 1.2: Poor — holdings move together
+
+**Pairwise Correlation Heatmap Template**
+
+For each pair of top-10 holdings, estimate 1-year rolling correlation:
+
+```
+         AAPL   MSFT   GOOGL  AMZN   NVDA   JPM   XOM   GLD
+AAPL     1.00   0.85   0.82   0.79   0.76   0.42  0.15  -0.10
+MSFT     0.85   1.00   0.84   0.80   0.78   0.41  0.14  -0.12
+GOOGL    0.82   0.84   1.00   0.81   0.73   0.39  0.12  -0.09
+AMZN     0.79   0.80   0.81   1.00   0.70   0.37  0.10  -0.08
+NVDA     0.76   0.78   0.73   0.70   1.00   0.35  0.11  -0.07
+JPM      0.42   0.41   0.39   0.37   0.35   1.00  0.48   0.05
+XOM      0.15   0.14   0.12   0.10   0.11   0.48  1.00   0.30
+GLD     -0.10  -0.12  -0.09  -0.08  -0.07   0.05  0.30  1.00
+```
+
+Color code: > 0.75 = HIGH (red), 0.50–0.75 = MODERATE (yellow), < 0.50 = LOW (green)
+
+**Effective Number of Positions (ENP)**
+
+ENP = 1 / sum(wi²) where wi = weight of position i
+
+Interpretation:
+- ENP ≈ actual N: equal-weight, low correlation — true diversification
+- ENP << actual N: dominated by a few large/correlated positions
+- Target ENP: at least 0.6 × actual number of holdings
+
+**Correlated Cluster Identification**
+
+Group holdings with pairwise correlation > 0.75 into clusters. Each cluster behaves as a single economic bet. Example clusters: Big Tech, Energy Majors, Regional Banks, Long-Duration Fixed Income.
+
+Actionable rule: no single cluster should exceed 35% of portfolio weight.
+
+## Phase 7 — Tax-Loss Harvesting Opportunities
+
+**Identification Criteria**
+
+Screen all positions for:
+1. Unrealized loss > 10% of cost basis
+2. Position held > 30 days (avoid wash-sale complications)
+3. Realized gains available to offset in the current tax year
+
+**Wash-Sale Rule (30-Day Rule)**
+
+Do not repurchase the same or substantially identical security within 30 days before or after the sale. Alternatives to maintain exposure during the 30-day window: sell XOM, buy CVX; sell QQQ, buy VGT; sell one S&P 500 ETF for another.
+
+**Net Tax Benefit Calculation**
+
+```
+Gross Tax Saving = Realized Loss × Marginal Tax Rate
+Transaction Cost  = (Bid-Ask Spread + Commission) × 2
+Net Benefit       = Gross Tax Saving − Transaction Cost
+Harvest if:       Net Benefit > 0 AND loss > $500 minimum threshold
+```
+
+**Tax-Loss Harvest Decision Table**
+
+| Condition | Action |
+|-----------|--------|
+| Unrealized loss > 10%, gains to offset, loss > $500 | Harvest — sell and replace with correlated substitute |
+| Unrealized loss 5–10%, gains to offset | Evaluate: transaction cost vs. tax saving |
+| Unrealized loss > 10%, no offsetting gains | Hold or carry forward — harvest at year-end if gains materialize |
+| Position held < 30 days | Wait for 30-day window to avoid wash-sale |
+| Loss < $500 | Skip — transaction costs exceed benefit |
+| Short-term gain offset | Priority harvest — short-term rates are higher |
+
+**Annual Harvest Tracking**
+
+Maintain a log: position, cost basis, current value, loss amount, harvest date, replacement security, re-entry date. Review in October before year-end to maximize benefit.
+
+## Phase 8 — Factor Exposure Analysis
+
+**Six-Factor Portfolio Map**
+
+For each holding, estimate factor scores (1–5 scale, 3 = neutral):
+
+| Factor | Measurement Proxy | Low (1–2) | Neutral (3) | High (4–5) |
+|--------|------------------|-----------|-------------|------------|
+| Value  | P/E, P/B vs. sector | Expensive | Fair | Cheap |
+| Growth | Revenue/EPS CAGR 3Y | < 5% | 5–15% | > 15% |
+| Momentum | 12-1 month return | Bottom quartile | Middle | Top quartile |
+| Quality | ROE, Debt/EBITDA | Low ROE, high debt | Average | High ROE, low debt |
+| Low-Vol | 1Y realized vol | High vol | Average | Low vol |
+| Size | Market cap | Mega-cap | Mid-cap | Small-cap |
+
+**Portfolio-Level Factor Score**
+
+Weight each holding's factor score by portfolio weight. Compare to S&P 500 baseline (all factors = 3.0):
+
+```
+Factor      Portfolio Score   Benchmark   Active Tilt
+Value           2.1              3.0       -0.9  (Growth tilt)
+Growth          4.2              3.0       +1.2  (Strong growth)
+Momentum        3.8              3.0       +0.8  (Slight momentum)
+Quality         3.5              3.0       +0.5  (Slight quality)
+Low-Vol         2.3              3.0       -0.7  (Higher volatility)
+Size            2.4              3.0       -0.6  (Large-cap tilt)
+```
+
+**Unintended Factor Tilt Detection**
+
+Flag when any active tilt exceeds ±1.0: this signals an unintended concentration that may not be in the investment thesis. Common unintended tilts: growth investors inadvertently loading up on momentum; dividend investors loading up on low-vol (rate sensitive); index investors with large-cap tilt through tech sector overweight.
+
+**Benchmark Factor Comparison**
+
+Use the factor tilts to explain return difference from benchmark. Growth tilt +1.2 in a value-outperforming market explains underperformance. Momentum tilt in a mean-reverting market increases drawdown risk.
+
+

package/selected-skills/InvestSkill/plugins/us-stock-analysis/skills/portfolio-review/references/12-phase-9-rebalancing-decision.md

@@ -0,0 +1,153 @@
+# Phase 9 — Rebalancing Decision Framework
+
+Part 3 of 4 for `portfolio-review` — Phase 9 — Rebalancing Decision Framework; Phase 10 — Drawdown & Risk Budget Analysis; Phase 11 — Optimization Recommendations; Output Format
+See `SKILL.md` for what to read and when; this part is procedure, not routing.
+
+## Phase 9 — Rebalancing Decision Framework
+
+**When to Rebalance**
+
+Three trigger systems — use the one matching the investor's approach:
+
+1. **Threshold-Based (Recommended for most investors)**
+   - Rebalance when any asset class drifts > 5% from target weight
+   - Individual stock position drifts > 3% from target
+   - No action if drift is within tolerance band
+
+2. **Calendar-Based**
+   - Review quarterly; rebalance only if drift > 3%
+   - Annual full rebalance regardless of drift
+   - Simpler but may miss significant mid-quarter moves
+
+3. **Factor-Based**
+   - Rebalance when portfolio factor score diverges > 1.5 from target
+   - Triggered by momentum factor decay (top-quartile stocks reversing)
+   - Suitable for factor-aware investors
+
+**Cost-Benefit Analysis**
+
+Before executing any rebalance, verify it clears the cost hurdle:
+
+```
+Expected Drift Cost (annual) = Excess vol from drift × Sharpe ratio penalty
+Transaction Cost = Commission + (Bid-Ask Spread × Trade Size) + Tax Impact
+Rebalance if: Drift Cost > Transaction Cost × 2 (safety margin)
+```
+
+Rule of thumb: do not rebalance positions with < $2,000 drift — transaction costs exceed benefit.
+
+**Rebalancing Decision Flowchart**
+
+```
+START
+  |
+  v
+Is drift > threshold?
+  NO  --> Monitor next period
+  YES --> Is account taxable?
+            YES --> Are there harvesting opportunities?
+                      YES --> Combine harvest + rebalance
+                      NO  --> Evaluate tax cost of rebalance
+                               Tax cost > drift benefit? --> Delay
+                               Tax cost < drift benefit? --> Rebalance
+            NO  --> Rebalance immediately (no tax friction)
+```
+
+**Tax-Smart Rebalancing Order**
+
+1. Use new cash contributions to buy underweight assets first
+2. Reinvest dividends into underweight positions
+3. Harvest losses in overweight positions to fund purchases
+4. If still needed, sell overweight positions (minimize short-term gains)
+
+## Phase 10 — Drawdown & Risk Budget Analysis
+
+**Per-Position Maximum Drawdown**
+
+For each holding, calculate the worst peak-to-trough decline over the analysis window:
+
+| Position | Max Drawdown | Recovery Time | Current From Peak | Risk Level |
+|----------|-------------|---------------|-------------------|-----------|
+| Example  | -35%        | 14 months     | -8%               | Medium |
+
+Flag positions with max drawdown > 50%: high-volatility securities require smaller position sizes to avoid outsized portfolio impact.
+
+**Portfolio-Level Value at Risk (VaR)**
+
+95% VaR (1-day): the loss not exceeded on 95% of trading days.
+
+Parametric VaR (simplified) = Portfolio Value × Portfolio Daily Vol × 1.645
+
+Example: $500,000 portfolio, daily vol 0.9% → 95% VaR = $500,000 × 0.009 × 1.645 = $7,403/day
+
+Report also: 99% VaR (multiply by 2.326 / 1.645) and 10-day VaR (multiply by √10).
+
+**Contribution to Portfolio Volatility**
+
+Each position's marginal contribution to total portfolio volatility:
+
+```
+Marginal Vol Contribution (i) = weight(i) × Cov(i, portfolio) / Portfolio Vol
+% Vol Contribution = Marginal Vol Contribution / Portfolio Vol × 100
+```
+
+Target: no single position contributes > 20% of total portfolio volatility unless it is a deliberate high-conviction overweight.
+
+**Risk Budget Allocation Table**
+
+| Position | Weight % | Vol Contribution % | Risk Budget Used | Status |
+|----------|----------|--------------------|-----------------|--------|
+| Ideal    | ≤ 10%    | ≤ 15%              | ≤ budget        | OK |
+| Flag     | > 10%    | > 20%              | Over budget     | Trim |
+
+**Stress Test Scenarios**
+
+Apply historical shock scenarios to estimate portfolio impact:
+- 2022 Rate Shock: tech -35%, bonds -15%, energy +50%
+- 2020 COVID Crash: market -34% in 33 days, recovery 5 months
+- 2008 GFC: market -57%, credit spreads +500bps
+- 2000 Dot-com: tech -78% over 2.5 years
+
+For each scenario: estimate portfolio decline, identify worst-hit positions, confirm portfolio can withstand the scenario without forcing a distressed sale.
+
+## Phase 11 — Optimization Recommendations
+
+1. **Rebalancing Actions**
+   - List all positions with > 2% drift from target weight
+   - Priority order: largest drift first
+   - Tax-aware rebalancing: prioritize tax-loss harvesting in taxable accounts
+   - Proposed trades: ticker, action (buy/sell/trim), target weight, estimated proceeds
+
+2. **Diversification Improvements**
+   - Specific gaps to fill (e.g., no international exposure, no inflation hedge)
+   - Correlation-reduction swaps: replace redundant holdings with uncorrelated alternatives
+   - Alternative asset candidates if appropriate (gold, TIPS, REITs, private credit proxies)
+
+3. **Underperformer Review**
+   - For each position underperforming benchmark by > 10% over 1Y:
+     - Is the original thesis intact?
+     - Has fundamentals deteriorated or is this a temporary setback?
+     - Hold / average down / exit decision with rationale
+
+4. **Upgrade Candidates**
+   - Positions to add based on current conviction and valuation
+   - New opportunities that fit the portfolio's existing factor tilts
+   - Cost reduction opportunities (replace active fund with cheaper ETF equivalent)
+
+## Output Format
+
+Deliver the review as a structured report with these sections:
+1. Executive Summary (3–5 bullet points: biggest strengths and risks)
+2. Performance Scorecard (table: metric | portfolio | benchmark | delta)
+3. Allocation Heat Map (sector/geography breakdown in table form)
+4. Concentration Risk Score (aggregate score with dimension breakdown)
+5. Factor Exposure Summary (six-factor table vs. benchmark)
+6. Holdings Table (position | weight | 1Y return | vol contribution % | status: hold/trim/exit)
+7. Tax-Loss Harvest Candidates (position | unrealized loss | estimated tax saving)
+8. Risk Budget Table (position | weight | vol contribution | status)
+9. Action List (prioritized, with expected portfolio impact)
+10. Implementation Roadmap (immediate / 30-day / 90-day actions)
+
+Focus on actionable insights aligned with the investor's stated objectives and risk tolerance. Flag any positions or allocations that conflict with the investor profile.
+
+

package/selected-skills/InvestSkill/plugins/us-stock-analysis/skills/portfolio-review/references/13-data-verification.md

@@ -0,0 +1,62 @@
+# Data Verification
+
+Part 4 of 4 for `portfolio-review` — Data Verification; Thesis Invalidation; Standard Signal Output
+See `SKILL.md` for what to read and when; this part is procedure, not routing.
+
+## Data Verification
+
+Before finalizing the analysis, verify:
+- [ ] Position weights sum to 100% (or account for cash)
+- [ ] Return figures use total return (dividends reinvested)
+- [ ] Benchmark used matches portfolio's investment universe
+- [ ] Correlation estimates based on at least 1 year of data
+- [ ] Tax calculations use correct marginal rate for the investor
+- [ ] Factor scores sourced from consistent data provider
+- [ ] VaR calculation uses current portfolio weights, not stale data
+
+## Thesis Invalidation
+
+A portfolio review is a plan, and plans expire. After the signal, state what would make this review's action list wrong:
+
+**If the signal is BULLISH (portfolio is well-positioned) — thesis breaks if:**
+- Any single position breaches the concentration limit set in this review (state the % and the ticker)
+- Realized correlation between the top holdings rises above the level assumed in the risk-budget table (diversification that only exists on paper)
+- The investor's stated objective or horizon changes — a portfolio built for accumulation is wrong for drawdown
+
+**If the signal is BEARISH (portfolio needs repair) — thesis breaks if:**
+- The flagged positions are trimmed or hedged as recommended and the risk-budget table re-balances
+- The concentration that drove the call resolves through price (the over-weight position falls) rather than through action — re-check before selling into weakness
+- The benchmark used turns out to be the wrong universe for the mandate
+
+**Re-run this review when:**
+- [ ] Quarter-end (rebalance check)
+- [ ] Any position moves more than ±25% relative to the portfolio
+- [ ] A contribution or withdrawal larger than 10% of portfolio value
+- [ ] Tax-year end (harvest window)
+- [ ] The investor's objectives, income needs, or horizon change
+
+## Standard Signal Output
+
+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)
+
+**Disclaimer:** Educational analysis only. Not financial advice.
+
+