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

Aspect	Market Breadth Analyzer	Breadth Chart Analyst
Data Source	CSV (automated)	Chart images (manual)
API Required	None	None
Output	Quantitative 0-100 score	Qualitative chart analysis
Components	6 scored dimensions	Visual pattern recognition
Repeatability	Fully reproducible	Analyst-dependent

---

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

#	Component	Weight	Key Signal
1	Breadth Level & Trend	25%	Current 8MA level + 200MA trend direction + 8MA direction modifier
2	8MA vs 200MA Crossover	20%	Momentum via MA gap and direction
3	Peak/Trough Cycle	20%	Position in breadth cycle
4	Bearish Signal	15%	Backtested bearish signal flag
5	Historical Percentile	10%	Current vs full history distribution
6	S&P 500 Divergence	10%	Multi-window (20d + 60d) price vs breadth divergence

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.

ヘルスゾーンのマッピング（100 = 健全）

スコア	ゾーン	株式エクスポージャー	アクション
80-100	強い	90-100%	フルポジションとし、成長・モメンタムを優先
60-79	健全	75-90%	通常運用
40-59	中立	60-75%	選択的にポジションを取り、ストップを引き締める
20-39	弱まりつつある	40-60%	利益確定し、現金比率を高める
0-19	危機的	25-40%	資本保全を優先し、底値を注視する

---

データソース

詳細 CSV: market_breadth_data.csv

• 2016-02 から現在までの約2,500行
• 列: Date, S&P500_Price, Breadth_Index_Raw, Breadth_Index_200MA, Breadth_Index_8MA, Breadth_200MA_Trend, Bearish_Signal, Is_Peak, Is_Trough, Is_Trough_8MA_Below_04

サマリー CSV: market_breadth_summary.csv

• 8つの集計指標（ピークの平均、トラフの平均、件数、分析期間）

どちらも GitHub Pages で公開されており、認証は不要です。

出力ファイル

• JSON: market_breadth_YYYY-MM-DD_HHMMSS.json
• Markdown: market_breadth_YYYY-MM-DD_HHMMSS.md
• 履歴: market_breadth_history.json（実行をまたいで保持、最大20件）

参考ドキュメント

references/breadth_analysis_methodology.md

• 構成要素のスコアリング詳細を含む完全な方法論
• しきい値の説明とゾーンの定義
• 過去の状況と解釈ガイド

参考資料を読み込むタイミング

• 初回使用時: 方法論の参考資料を読み込み、フレームワークを理解します
• 通常の実行時: 参考資料は不要です。スクリプトがスコアリングを処理します

同一実行の来歴情報

両方の必須の market-regime-daily プロデューサーに --run-id daily-20261017-unique を渡してください。指定しない場合、各プロデューサーはそれぞれ固有の ID を生成します。JSON にはスキーマ 1.0 の data_provenance が含まれ、実際の主要時系列データの営業日、UTC での取得時刻、ソース、実行 ID が記録されます。調整、ポイント・イン・タイム、サバイバーシップ、コーポレートアクションに関するフラグは、いずれも不明として false に設定されます。補助的なサマリーの日付は未検証です。この情報は、すべての複合入力データが最新であることを証明するものではありません。主要データの日付が欠落しているか不正な形式の場合、レポートの生成は中止されます。

これらの実行で出力された JSON のパスを正確に Exposure Coach の --require-provenance --run-id … --as-of … モードに渡してください。実行 ID は呼び出し元が指定する整合性マーカーであり、真正性やポイント・イン・タイムを証明するものではありません。