market-top-detector

Market Top Detector Skill

Purpose

Assess heuristic market top risk using a 6-component scoring system (0-100). Integrates three market risk methodologies:

1. O'Neil - Distribution Day accumulation (institutional selling)
2. Minervini - Leading stock deterioration pattern
3. Monty - Defensive sector rotation signal

Unlike the Bubble Detector (macro/multi-month evaluation), this skill focuses on tactical 2-8 week timing signals that precede 10-20% market corrections.

Score interpretation

Treat the 0-100 composite as a heuristic risk score, not an estimated event probability. A score of 70 does not mean a 70% chance of a top. Risk-budget percentages are policy heuristics, not measured outcome frequencies. Historical patterns are retrospective estimates, not point-in-time evidence. Report no comparable episode when any component is unavailable/invalid or nearest-pattern weighted RMS exceeds 15 points. This tolerance is a predeclared heuristic, not an empirically validated similarity threshold. Follow the point-in-time evaluation protocol before making calibration claims. No measured calibration results are supplied.

When to Use This Skill

English:

• User asks "Is the market topping?" or "Are we near a top?"
• User notices distribution days accumulating
• User observes defensive sectors outperforming growth
• User sees leading stocks breaking down while indices hold
• User asks about reducing equity exposure timing
• User wants to assess correction risk for the next 2-8 weeks

Japanese:

• 「天井が近い？」「今は利確すべき？」
• ディストリビューションデーの蓄積を懸念
• ディフェンシブセクターがグロースをアウトパフォーム
• 先導株が崩れ始めているが指数はまだ持ちこたえている
• エクスポージャー縮小のタイミング判断
• 今後2〜8週間の調整リスクを評価したい

Prerequisites

Required:

• FMP API Key: Set $FMP_API_KEY environment variable or pass --api-key. Free tier sufficient (~33 API calls per execution).
• WebSearch Access: Required to collect S&P 500 breadth (50DMA %) and CBOE Put/Call ratio data.

Optional:

• Margin Debt Data: Enhances sentiment scoring but typically 1-2 months lagged.
• VIX Term Structure: Auto-detected from FMP API if VIX3M quote available; manual override via --vix-term.

Data Freshness: All manually collected data should be from the most recent 3 business days for accurate analysis.

Difference from Bubble Detector

Aspect	Market Top Detector	Bubble Detector
Timeframe	2-8 weeks	Months to years
Target	10-20% correction	Bubble collapse (30%+)
Methodology	O'Neil/Minervini/Monty	Minsky/Kindleberger
Data	Price/Volume + Breadth	Valuation + Sentiment + Social
Score Range	0-100 composite	0-15 points

---

Execution Workflow

Phase 1: Data Collection via WebSearch

Before running the Python script, collect the following data using WebSearch. Data Freshness Requirement: All data must be from the most recent 3 business days. Stale data degrades analysis quality.

1. S&P 500 Breadth (200DMA above %)
   AUTO-FETCHED from TraderMonty CSV (no WebSearch needed)
   The script fetches this automatically from GitHub Pages CSV data.
   Override: --breadth-200dma [VALUE] to use a manual value instead.
   Disable: --no-auto-breadth to skip auto-fetch entirely.

2. [REQUIRED] S&P 500 Breadth (50DMA above %)
   Valid range: 20-100
   Primary search: "S&P 500 percent stocks above 50 day moving average"
   Fallback: "market breadth 50dma site:barchart.com"
   Direct fallback when search snippets are poor: fetch `https://www.barchart.com/stocks/quotes/$S5FI/overview` and extract the embedded `lastPrice` / `tradeTime` for “S&P 500 Stocks Above 50-Day Average”.
   Record the data date

3. [REQUIRED] CBOE Equity Put/Call Ratio
   Valid range: 0.30-1.50
   Primary search: "CBOE equity put call ratio today"
   Fallback: "CBOE total put call ratio current"
   Fallback: "put call ratio site:cboe.com"
   Direct fallback when Cboe CSV endpoints are stale: fetch `https://ycharts.com/indicators/cboe_equity_put_call_ratio` and parse the “Last Value” / “Latest Period” table fields. Treat this as a secondary source and cite it in freshness notes.
   Record the data date

4. [OPTIONAL] VIX Term Structure
   Values: steep_contango / contango / flat / backwardation
   Primary search: "VIX VIX3M ratio term structure today"
   Fallback: "VIX futures term structure contango backwardation"
   Note: Auto-detected from FMP API if VIX3M quote available.
   CLI --vix-term overrides auto-detection.

5. [OPTIONAL] Margin Debt YoY %
   Primary search: "FINRA margin debt latest year over year percent"
   Fallback: "NYSE margin debt monthly"
   Note: Typically 1-2 months lagged. Record the reporting month.

Phase 2: Execute Python Script

Run the script with collected data as CLI arguments:

python3 skills/market-top-detector/scripts/market_top_detector.py \
  --api-key $FMP_API_KEY \
  --breadth-50dma [VALUE] --breadth-50dma-date [YYYY-MM-DD] \
  --put-call [VALUE] --put-call-date [YYYY-MM-DD] \
  --vix-term [steep_contango|contango|flat|backwardation] \
  --margin-debt-yoy [VALUE] --margin-debt-date [YYYY-MM-DD] \
  --output-dir reports/ \
  --context "Consumer Confidence=[VALUE]" "Gold Price=[VALUE]"
# 200DMA breadth is auto-fetched from TraderMonty CSV.
# Override with --breadth-200dma [VALUE] if needed.
# Disable with --no-auto-breadth to skip auto-fetch.

The script will:

1. Fetch S&P 500, QQQ, VIX quotes and history from FMP API
2. Fetch Leading ETF (ARKK, WCLD, IGV, XBI, SOXX, SMH, KWEB, TAN) data
3. Fetch Sector ETF (XLU, XLP, XLV, VNQ, XLK, XLC, XLY) data
4. Calculate all 6 components
5. Generate composite score and reports

Phase 3: Present Results

Present the generated Markdown report to the user, highlighting:

• Composite score and risk zone
• Data freshness warnings (if any data older than 3 days)
• Strongest warning signal (highest component score)
• Historical comparison (closest past top pattern)
• What-if scenarios (sensitivity to key changes)
• Recommended actions based on risk zone
• Follow-Through Day status (if applicable)
• Delta vs previous run (if prior report exists)

---

6要素スコアリングシステム

#	要素	ウェイト	データソース	主なシグナル
1	ディストリビューションデー数	25%	FMP API	過去25取引日における機関投資家の売り
2	主導株の健全性	20%	FMP API	成長株ETFバスケットの悪化
3	ディフェンシブセクターへの資金ローテーション	15%	FMP API	ディフェンシブ銘柄と成長株の相対パフォーマンス
4	市場の広がりの乖離	15%	Auto (CSV) + WebSearch	インデックス水準に対する200DMA（自動）／50DMA（WebSearch）の市場の広がり
5	インデックスのテクニカル状況	15%	FMP API	移動平均線の構造、失敗した反発、切り下がる高値
6	センチメントと投機	10%	FMP + WebSearch	VIX、プット／コール、期間構造

リスクゾーンの対応表

スコア	ゾーン	リスク予算	アクション
0-20	Green (Normal)	100%	通常運用
21-40	Yellow (Early Warning)	80-90%	ストップを引き締め、新規エントリーを減らす
41-60	Orange (Elevated Risk)	60-75%	弱いポジションの利益を確定する
61-80	Red (High Risk)	40-55%	積極的に利益を確定する
81-100	Critical (Very High Risk)	20-35%	最大限の防御とヘッジ

---

取引所カレンダーとリプレイ

検出器を実行する前に requirements.txt をインストールしてください。データの鮮度判定には平日ではなく、XNYSの取引セッションを使用します。--as-of YYYY-MM-DD はライブ評価日として指定できますが、現在の株価エンドポイントは特定時点のデータソースではないため、過去の日付を指定したライブリプレイは安全のため実行されません。

API要件

必須： FMP APIキー（無料枠で十分です。実行1回あたり約33回の呼び出し） 任意： 市場の広がりとセンチメントのWebSearchデータ（精度が向上します）

出力ファイル

• JSON：market_top_YYYY-MM-DD_HHMMSS.json
• Markdown：market_top_YYYY-MM-DD_HHMMSS.md

参考資料

references/market_top_methodology.md

• O'Neil、Minervini、Montyのフレームワークを含む完全な手法
• 要素別のスコアリングの詳細と閾値
• 過去の検証に関する注記

references/distribution_day_guide.md

• O'Neilのディストリビューションデーに関する詳細なルール
• 失速日の特定
• フォロースルーデー（FTD）の仕組み

references/historical_tops.md

• 2000年、2007年、2018年、2022年の相場の天井の分析
• 過去の天井における要素別スコアのパターン
• 得られた教訓と回顧的な参考推定値

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

• 初回使用時： フレームワーク全体を理解するため、market_top_methodology.md を読み込みます
• ディストリビューションデーに関する質問： distribution_day_guide.md を読み込みます
• 過去の状況を確認する場合： historical_tops.md を読み込みます
• 通常の実行時： スクリプトがスコアリングを処理するため、参考資料は不要です