market-top-detector

Market Top Detector Skill

Purpose

Detect the probability of a market top formation using a quantitative 6-component scoring system (0-100). Integrates three proven market top detection 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.

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 probability 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"
   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"
   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-Component Scoring System

#	Component	Weight	Data Source	Key Signal
1	Distribution Day Count	25%	FMP API	Institutional selling in last 25 trading days
2	Leading Stock Health	20%	FMP API	Growth ETF basket deterioration
3	Defensive Sector Rotation	15%	FMP API	Defensive vs Growth relative performance
4	Market Breadth Divergence	15%	Auto (CSV) + WebSearch	200DMA (auto) / 50DMA (WebSearch) breadth vs index level
5	Index Technical Condition	15%	FMP API	MA structure, failed rallies, lower highs
6	Sentiment & Speculation	10%	FMP + WebSearch	VIX, Put/Call, term structure

リスクゾーンマッピング

スコア	ゾーン	リスクバジェット	アクション
0-20	グリーン (通常)	100%	通常の運用
21-40	イエロー (早期警告)	80-90%	ストップを厳格化し、新規エントリーを削減
41-60	オレンジ (リスク上昇)	60-75%	弱いポジションの利益確定
61-80	レッド (高確率の天井)	40-55%	積極的な利益確定
81-100	クリティカル (天井形成)	20-35%	最大限の防御、ヘッジ

---

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 を読み込む
• 通常の実行: 参照ドキュメントは不要 - スクリプトがスコアリングを処理します