market-breadth-analyzer

Market Breadth Analyzer Skill

Purpose

Quantify market breadth health using a data-driven 6-component scoring system (0-100). Uses TraderMonty's publicly available CSV data to measure how broadly the market is participating in a rally or decline.

Score direction: 100 = Maximum health (broad participation), 0 = Critical weakness.

No API key required - uses freely available CSV data from GitHub Pages.

When to Use This Skill

English:

• User asks "Is the market rally broad-based?" or "How healthy is market breadth?"
• User wants to assess market participation rate
• User asks about advance-decline indicators or breadth thrust
• User wants to know if the market is narrowing (fewer stocks participating)
• User asks about equity exposure levels based on breadth conditions

Japanese:

• 「マーケットブレッドスはどうですか？」「市場の参加率は？」
• 「上昇は広がっている？」「一部の銘柄だけの上昇？」
• ブレッドス指標に基づくエクスポージャー判断
• 市場の健康度をデータで確認したい

Prerequisites

• Python 3.9+ with requests library (for fetching CSV data)
• Internet access to reach GitHub Pages URLs
• No API keys required - uses freely available public CSV data

Difference from Breadth Chart Analyst

Execution Workflow

Phase 1: Execute Python Script

Run the analysis script. If using a nested or date-stamped --output-dir in cron runs, create it first; the history writer expects the directory to already exist.

mkdir -p reports/<routine-or-date>
python3 skills/market-breadth-analyzer/scripts/market_breadth_analyzer.py \
  --detail-url "https://tradermonty.github.io/market-breadth-analysis/market_breadth_data.csv" \
  --summary-url "https://tradermonty.github.io/market-breadth-analysis/market_breadth_summary.csv" \
  --output-dir reports/<routine-or-date>

For a simple ad-hoc run, omit --output-dir or use an existing directory. In scheduled cron runs from the repository root, prefer a repo-relative output directory such as reports/after-close-YYYY-MM-DD rather than an absolute path. If an absolute nested --output-dir unexpectedly fails at the history-writing step despite the directory existing, rerun once with the equivalent repo-relative path before treating the breadth analysis as unavailable.

The script will:

1. Fetch detail CSV (~2,500 rows, 2016-present) and summary CSV (8 metrics)
2. Validate data freshness (warn if > 5 days old)
3. Calculate all 6 component scores (with automatic weight redistribution if any component lacks data)
4. Generate composite score with zone classification
5. Track score history and compute trend (improving/deteriorating/stable)
6. Output JSON and Markdown reports

Phase 2: Present Results

Present the generated Markdown report to the user, highlighting:

• Composite score and health zone
• Strongest and weakest components
• Recommended equity exposure level
• Key breadth levels to watch
• Any data freshness warnings

6-Component Scoring System

Weight Redistribution: If any component lacks sufficient data (e.g., no peak/trough markers detected), it is excluded and its weight is proportionally redistributed among the remaining components. The report shows both original and effective weights.

Score History: Composite scores are persisted across runs (keyed by data date). The report includes a trend summary (improving/deteriorating/stable) when multiple observations are available.

Health Zone Mapping (100 = Healthy)

Data Sources

Detail CSV: market_breadth_data.csv

• ~2,500 rows from 2016-02 to present
• Columns: Date, S&P500Price, BreadthIndexRaw, BreadthIndex200MA, BreadthIndex8MA, Breadth200MATrend, BearishSignal, IsPeak, IsTrough, IsTrough8MABelow04

Summary CSV: market_breadth_summary.csv

• 8 aggregate metrics (average peaks, average troughs, counts, analysis period)

Both are publicly hosted on GitHub Pages - no authentication required.

Output Files

• JSON: market_breadth_YYYY-MM-DD_HHMMSS.json
• Markdown: market_breadth_YYYY-MM-DD_HHMMSS.md
• History: market_breadth_history.json (persists across runs, max 20 entries)

Reference Documents

references/breadth_analysis_methodology.md

• Full methodology with component scoring details
• Threshold explanations and zone definitions
• Historical context and interpretation guide

When to Load References

• First use: Load methodology reference for framework understanding
• Regular execution: References not needed - script handles scoring

Same-run provenance

Pass --run-id daily-20261017-unique to both required market-regime-daily producers. Without it each producer generates its own unique ID. JSON includes schema 1.0 data_provenance with actual primary timeseries business date, UTC retrieval time, source and run ID. Unknown adjustment, point-in-time, survivorship and corporate-action flags are false. Auxiliary summary dates are unverified; this does not certify the freshness of every composite input. Missing or malformed primary dates stop report generation.

Pass the exact JSON paths printed by these invocations to Exposure Coach's --require-provenance --run-id … --as-of … mode. Run IDs are caller-provided consistency markers, not authenticity or point-in-time proof.