Exposure Coach

Overview

Exposure Coach synthesizes outputs from market-breadth-analyzer, uptrend-analyzer, macro-regime-detector, market-top-detector, ftd-detector, theme-detector, sector-analyst, and institutional-flow-tracker into a unified control-plane decision. The skill answers the solo trader's core question: "How much capital should I commit to equities right now?" before any individual stock analysis begins.

When to Use

• Before initiating any new stock positions to determine appropriate capital commitment
• At the start of each trading week to calibrate portfolio exposure
• When multiple market signals conflict and a unified posture is needed
• After significant macro or market events to reassess exposure ceiling
• When transitioning between market regimes (broadening, concentration, contraction)

Prerequisites

• Python 3.9+
• FMP API key (set FMPAPIKEY environment variable) for institutional-flow-tracker data
• Input JSON files from upstream skills (see Workflow Step 1)
• Standard library + argparse, json, datetime

Workflow

Step 1: Gather Upstream Skill Outputs

Collect the most recent JSON outputs from integrated skills. Each file provides a specific signal dimension:

Step 2: Run Exposure Scoring Engine

Execute the exposure scoring script with paths to upstream outputs:

python3 skills/exposure-coach/scripts/calculate_exposure.py \
  --breadth reports/breadth_latest.json \
  --uptrend reports/uptrend_latest.json \
  --regime reports/regime_latest.json \
  --top-risk reports/top_risk_latest.json \
  --ftd reports/ftd_latest.json \
  --theme reports/theme_latest.json \
  --sector reports/sector_latest.json \
  --institutional reports/institutional_latest.json \
  --output-dir reports/

The script accepts partial inputs; missing files reduce confidence but do not block execution.

Canonical macro-regime reports must include nested regime.confidence and composite.dataquality with valid integer component counts. Missing or malformed availability metadata, verylow confidence, and zero usable components are treated as missing critical input. They do not contribute a regime score or bias, and the normal missing-input haircut and confidence cap apply. Never override this degradation by manually copying the report's regime label into the exposure decision.

Verification pitfall: After each run, inspect the generated JSON fields inputsprovided and inputsmissing. If a file you passed on the CLI still appears in inputs_missing (for example a theme-detector JSON that the exposure engine did not recognize), report the affected dimension as degraded and keep confidence capped; do not assume the supplied input was incorporated just because the CLI argument was present.

Theme-detector ingestion caveat: The theme detector commonly emits themedetectorYYYY-MM-DDHHMMSS.json with a themes object. If that file is not recognized by calculateexposure.py and theme remains in inputs_missing, do not fold theme strength into the exposure ceiling manually. Instead, keep the Exposure Coach confidence capped, state that the theme dimension was not incorporated, and summarize theme/sector findings separately in the broader trading brief.

Step 3: Interpret the Market Posture Summary

Review the generated posture report containing:

1. Exposure Ceiling -- Maximum recommended equity allocation (0-100%)
2. Bias Direction -- Growth vs Value tilt based on regime and flow
3. Participation Assessment -- Broad (healthy) vs Narrow (fragile) market
4. Action Recommendation -- NEWENTRYALLOWED, REDUCEONLY, or CASHPRIORITY
5. Confidence Level -- HIGH, MEDIUM, or LOW based on input completeness

Step 4: Apply Exposure Guidance

Map the posture recommendation to portfolio actions:

Output Format

JSON Report

{
  "schema_version": "1.0",
  "generated_at": "2026-03-16T07:00:00Z",
  "exposure_ceiling_pct": 70,
  "bias": "GROWTH",
  "participation": "BROAD",
  "recommendation": "NEW_ENTRY_ALLOWED",
  "confidence": "HIGH",
  "component_scores": {
    "breadth_score": 65,
    "uptrend_score": 72,
    "regime_score": 80,
    "top_risk_score": 25,
    "ftd_score": 10,
    "theme_score": 68,
    "sector_score": 70,
    "institutional_score": 75
  },
  "inputs_provided": ["breadth", "uptrend", "regime", "top_risk"],
  "inputs_missing": ["ftd", "theme", "sector", "institutional"],
  "rationale": "Broad participation with low top risk supports elevated exposure."
}

Markdown Report

The markdown report provides a one-page summary suitable for quick review:

# Market Posture Summary
**Date:** 2026-03-16 | **Confidence:** HIGH

## Exposure Ceiling: 70%

| Dimension | Score | Status |
|-----------|-------|--------|
| Breadth | 65 | Healthy |
| Uptrend Participation | 72% | Broad |
| Regime | Broadening | Favorable |
| Top Risk | 25 | Low |

## Recommendation: NEW_ENTRY_ALLOWED

**Bias:** Growth > Value
**Participation:** Broad (healthy internals)

### Rationale
Broad participation with low distribution day count supports elevated equity exposure.
New positions allowed within the 70% ceiling.

Reports are saved to reports/ with filenames exposurepostureYYYY-MM-DD_HHMMSS.{json,md}.

Resources

• scripts/calculate_exposure.py -- Main orchestrator that scores and synthesizes inputs
• references/exposure_framework.md -- Scoring rules and threshold definitions
• references/regimeexposuremap.md -- Regime-to-exposure ceiling mappings

Key Principles

1. Safety First -- Default to lower exposure when inputs are incomplete or conflicting
2. Regime Alignment -- Let macro regime set the baseline; breadth adjusts within bounds
3. Actionable Output -- Always produce a clear recommendation, not just data aggregation