Macro Regime Detector

Detect structural macro regime transitions using monthly-frequency cross-asset ratio analysis. This skill identifies 1-2 year regime shifts that inform strategic portfolio positioning.

When to Use

• User asks about current macro regime or regime transitions
• User wants to understand structural market rotations (concentration vs broadening)
• User asks about long-term positioning based on yield curve, credit, or cross-asset signals
• User references RSP/SPY ratio, IWM/SPY, HYG/LQD, or other cross-asset ratios
• User wants to assess whether a regime change is underway

Workflow

1. Load reference documents for methodology context:

   • references/regime_detection_methodology.md
   • references/indicator_interpretation_guide.md

2. Execute the main analysis script:

   uv run python3 skills/macro-regime-detector/scripts/macro_regime_detector.py --output-dir reports/

   This fetches 600 days of data for 9 ETFs + Treasury rates (~10 API calls total). An FMP API key is required to run this skill (the client raises if it is missing). For individual ETFs whose FMP historical-price endpoint returns nothing, the client automatically falls back to yfinance — this fallback needs no additional API key, but it does not remove the FMP key requirement.

3. Read the generated Markdown report and present findings to user.

4. Provide additional context using references/historical_regimes.md when user asks about historical parallels.

Prerequisites

• FMP API Key (required): Set FMP_API_KEY environment variable or pass --api-key
• Free tier (250 calls/day) is sufficient (script uses ~10 calls)

6 Components

5 Regime Classifications

• Concentration: Mega-cap leadership, narrow market
• Broadening: Expanding participation, small-cap/value rotation
• Contraction: Credit tightening, defensive rotation, risk-off
• Inflationary: Positive stock-bond correlation, traditional hedging fails
• Transitional: Multiple signals but unclear pattern

Output

• macro_regime_YYYY-MM-DD_HHMMSS.json — Structured data for programmatic use
• macro_regime_YYYY-MM-DD_HHMMSS.md — Human-readable report with:
  1. Current Regime Assessment
  2. Transition Signal Dashboard
  3. Component Details
  4. Regime Classification Evidence
  5. Portfolio Posture Recommendations

Relationship to Other Skills

Script Arguments

python3 macro_regime_detector.py [options]

Options:
  --api-key KEY       FMP API key (default: $FMP_API_KEY)
  --output-dir DIR    Output directory (default: current directory)
  --days N            Days of history to fetch (default: 600)

Resources

• references/regime_detection_methodology.md — Detection methodology and signal interpretation
• references/indicator_interpretation_guide.md — Guide for interpreting cross-asset ratios
• references/historical_regimes.md — Historical regime examples for context