Market Top Detector Skill

Purpose

マーケットトップ形成の確率を定量的な6要素スコアリングシステム（0-100）を使用して検出します。3つの実証済みマーケットトップ検出方法論を統合します：

1. O'Neil - ディストリビューションデーの蓄積（機関投資家の売却）
2. Minervini - 先導株悪化パターン
3. Monty - ディフェンシブセクターローテーション信号

バブル検出スキル（マクロ/複数月の評価）とは異なり、このスキルは10-20%の市場調整に先行する2〜8週間のタクティカルなタイミング信号に焦点を当てています。

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: $FMP_API_KEY 環境変数を設定するか、--api-key で指定します。フリーティアで十分です（実行あたり約33 API呼び出し）。
• WebSearch Access: S&P 500のブレッドス（50DMA %）とCBOE プット/コール比率データを収集するために必須です。

Optional:

• Margin Debt Data: センチメントスコアリングを強化しますが、通常1〜2ヶ月のラグがあります。
• VIX Term Structure: FMP APIから自動検出されます（VIX3M クォートが利用可能な場合）。--vix-term で手動上書き可能です。

Data Freshness: すべての手動収集データは、正確な分析のために最新の3営業日以内のものである必要があります。

Difference from Bubble Detector

Aspect	Market Top Detector	Bubble Detector
Timeframe	2-8週間	数ヶ月〜数年
Target	10-20%調整	バブル崩壊（30%以上）
Methodology	O'Neil/Minervini/Monty	Minsky/Kindleberger
Data	Price/Volume + Breadth	Valuation + Sentiment + Social
Score Range	0-100複合スコア	0-15ポイント

---

Execution Workflow

Phase 1: WebSearchによるデータ収集

Pythonスクリプトを実行する前に、WebSearchを使用して以下のデータを収集します。 データ新鮮性要件: すべてのデータは最新の3営業日以内である必要があります。古いデータは分析品質を低下させます。

1. S&P 500 Breadth (200DMA above %)
   AUTO-FETCHED from TraderMonty CSV (WebSearch不要)
   スクリプトはGitHub Pages CSVデータから自動的にこれを取得します。
   上書き: --breadth-200dma [VALUE] で手動値を使用します。
   無効化: --no-auto-breadth で自動取得をスキップします。

2. [REQUIRED] S&P 500 Breadth (50DMA above %)
   有効範囲: 20-100
   主な検索: "S&P 500 percent stocks above 50 day moving average"
   代替案: "market breadth 50dma site:barchart.com"
   データ日付を記録します

3. [REQUIRED] CBOE Equity Put/Call Ratio
   有効範囲: 0.30-1.50
   主な検索: "CBOE equity put call ratio today"
   代替案: "CBOE total put call ratio current"
   代替案: "put call ratio site:cboe.com"
   データ日付を記録します

4. [OPTIONAL] VIX Term Structure
   値: steep_contango / contango / flat / backwardation
   主な検索: "VIX VIX3M ratio term structure today"
   代替案: "VIX futures term structure contango backwardation"
   注: VIX3M クォートが利用可能な場合、FMP APIから自動検出されます。
   CLI --vix-term が自動検出を上書きします。

5. [OPTIONAL] Margin Debt YoY %
   主な検索: "FINRA margin debt latest year over year percent"
   代替案: "NYSE margin debt monthly"
   注: 通常1〜2ヶ月のラグがあります。報告月を記録します。

Phase 2: Pythonスクリプトの実行

収集したデータをCLI引数として実行します：

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 ブレッドスはTraderMonty CSVから自動取得されます。
# 必要に応じて --breadth-200dma [VALUE] で上書きします。
# --no-auto-breadth で自動取得をスキップします。

スクリプトは以下を実行します：

1. FMP APIからS&P 500、QQQ、VIXクォートと履歴を取得
2. 先導ETF（ARKK、WCLD、IGV、XBI、SOXX、SMH、KWEB、TAN）のデータを取得
3. セクターETF（XLU、XLP、XLV、VNQ、XLK、XLC、XLY）のデータを取得
4. 全6要素を計算
5. 複合スコアとレポートを生成

Phase 3: 結果の提示

生成されたMarkdownレポートをユーザーに提示し、以下を強調します：

• 複合スコアとリスク区域
• データ新鮮性の警告（3日以上前のデータがある場合）
• 最強の警告信号（最高の要素スコア）
• 過去の比較（最も近い過去のトップパターン）
• What-ifシナリオ（主要な変化への感度）
• リスク区域に基づく推奨アクション
• Follow-Through Day ステータス（該当する場合）
• 前回の実行との差分（以前のレポートが存在する場合）

---

6-Component Scoring System

#	Component	Weight	Data Source	Key Signal
1	Distribution Day Count	25%	FMP API	過去25営業日間の機関投資家売却
2	Leading Stock Health	20%	FMP API	グロースETFバスケットの悪化
3	Defensive Sector Rotation	15%	FMP API	ディフェンシブ対グロースの相対パフォーマンス
4	Market Breadth Divergence	15%	Auto (CSV) + WebSearch	200DMA（自動）/ 50DMA（WebSearch）ブレッドス対指数レベル
5	Index Technical Condition	15%	FMP API	MA構造、失敗したラリー、安値の高さ
6	Sentiment & Speculation	10%	FMP + WebSearch	VIX、プット/コール、ターム構造

Risk Zone Mapping

Score	Zone	Risk Budget	Action
0-20	Green (Normal)	100%	通常の運用
21-40	Yellow (Early Warning)	80-90%	ストップを厳しくし、新規建て玉を減らす
41-60	Orange (Elevated Risk)	60-75%	弱いポジションの利食い
61-80	Red (High Probability Top)	40-55%	積極的な利食い
81-100	Critical (Top Formation)	20-35%	最大防御、ヘッジ

---

API Requirements

Required: FMP APIキー（フリーティアで十分：実行あたり約33呼び出し） Optional: ブレッドスとセンチメント用のWebSearchデータ（精度向上）

Output Files

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

Reference Documents

references/market_top_methodology.md

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

references/distribution_day_guide.md

• 詳細なO'Neil ディストリビューションデーのルール
• ストーリング日の識別
• Follow-Through Day（FTD）のメカニクス

references/historical_tops.md

• 2000年、2007年、2018年、2022年のマーケットトップの分析
• 過去のトップ時における要素スコアのパターン
• 教訓と較正データ

When to Load References

• 初回使用: market_top_methodology.md を読んで完全なフレームワークを理解します
• ディストリビューションデーに関する質問: distribution_day_guide.md を読みます
• 過去のコンテキスト: historical_tops.md を読みます
• 定期実行: 参照資料は不要です - スクリプトがスコアリングを処理します