monitor-etf-holdings-drawdown-risk

<essential_principles>

**乖離シグナルの基本ロジック**

乖離イベントの定義：

• 価格上昇：price_return >= min_price_return_pct（例：+15%）
• 在庫減少：inventory_change <= -min_inventory_drawdown_pct（例：-10%）
• 同時発生：同じ期間（例：180日）内に両方の条件を満たす

価格と在庫が同じ方向に動く場合（ともに上昇、またはともに下落）は正常です。逆方向に動く場合（価格上昇・在庫減少）に警戒が必要です。

**二つの仮説による検証**

「在庫減少」をそのまま「現物が買い占められている」と解釈することはできません。複数の指標で検証する必要があります。

仮説	支持する条件	反証する条件
現物の逼迫	COMEX/LBMAの在庫減少、バックワーデーション、リースレート上昇、小売プレミアム拡大	他の在庫は安定、コンタンゴ、小売プレミアムは横ばい
資金フロー／償還	ETFから資金が流出している一方、取引所の在庫は安定、先物の限月構成に逼迫がない	複数の在庫が同時に減少

二つの解釈を提示し、現在のデータにどちらがより当てはまるかをユーザーが判断できるようにします。

**データの取得方法**

このスキルでは、以下を優先して使用します。

• ETF公式サイトの保有在庫：Seleniumで人間のブラウザー操作を模倣して取得（API制限を回避）
• Yahoo Finance：yfinanceパッケージで現物／先物価格を取得
• クロスチェック：COMEX在庫、先物の限月構成などの公開データ

スクリプトは scripts/ ディレクトリにあり、references/data-sources.md の検出回避戦略に従います。

**ストレススコアの計算**

stress_score = 100 × min(1.0,
    0.6 × divergence_severity +      # 背離嚴重度
    0.2 × decade_low_bonus +         # 十年低點加成
    0.2 × ratio_extreme_bonus        # 比值極端加成
)

スコア範囲	解釈
0-30	正常。明確な乖離なし
30-60	軽度の乖離。注視が必要
60-80	中程度の乖離。詳しい検証を推奨
80-100	深刻な乖離。厳重な警戒が必要

</essential_principles>

現物型ETF（SLV、PSLV、GLDなど）の保有量と商品価格の乖離を監視します。

1. 乖離の検出：価格上昇とETF在庫の減少
2. 深刻度の評価：乖離の度合い、10年ぶりの安値、比率の極端な値を算出
3. クロスチェック：COMEX、先物の限月構成、小売プレミアムなどの指標を使用
4. 洞察の提示：一つの見方に偏らないよう、対立する二つの仮説を提示

出力：乖離の状態、ストレススコア、クロスチェック結果、次に確認すべき項目の提案。

<quick_start>

最速の方法：SLVの乖離状態を確認する

cd skills/monitor-etf-holdings-drawdown-risk
pip install pandas numpy yfinance selenium webdriver-manager beautifulsoup4 matplotlib  # 首次使用
python scripts/divergence_detector.py --etf SLV --quick

出力例：

{
  "asof": "2026-01-20",
  "divergence": false,
  "price_return_window": 1.92,
  "inventory_change_window": 0.15,
  "inventory_decade_low": false,
  "stress_score_0_100": 20.0,
  "interpretations": ["Physical Tightness", "ETF Flow Hypothesis"]
}

完全な分析＋可視化レポート：

# 1. 執行背離偵測
python scripts/divergence_detector.py \
  --etf SLV \
  --start 2010-01-01 \
  --end 2026-01-20 \
  --output result.json

# 2. 生成視覺化報告
python scripts/visualize_divergence.py \
  --result result.json \
  --output ../../../output/

出力：

• JSON分析結果：result.json
• 可視化レポート：output/SLV_divergence_report_20260120.png
• PDFレポート：output/SLV_divergence_report_20260120.pdf

</quick_start>

どの操作を実行しますか？

1. クイックチェック - 指定したETFの現在の乖離状態とストレススコアを確認
2. 完全な分析 - 乖離の履歴を完全に分析
3. クロスチェック - 複数の指標を使って乖離シグナルの真偽を検証
4. 監視モード - 継続的な監視と乖離アラートを設定
5. 方法論の学習 - 乖離の検出と二つの仮説による検証ロジックを確認

選択するか、分析パラメーター（ETFティッカーなど）を直接指定してください。

| 応答 | アクション | |---------------------------------|-----------------------------------------------| | 1, "快速", "quick", "check" | `scripts/divergence_detector.py --quick` を実行 | | 2, "分析", "analyze", "full" | `workflows/analyze.md` を読んで実行 | | 3, "驗證", "validate", "cross" | `workflows/cross-validate.md` を読んで実行 | | 4, "監控", "monitor", "alert" | `workflows/monitor.md` を読んで実行 | | 5, "學習", "方法論", "why" | `references/methodology.md` を読む | | ETFティッカーを指定（SLV、GLDなど） | `workflows/analyze.md` を読んで、パラメーターを指定して実行 |

ルーティング後、対応するファイルを読んで実行してください。

<directory_structure>

monitor-etf-holdings-drawdown-risk/
├── SKILL.md                           # 本文件（路由器）
├── skill.yaml                         # 前端展示元數據
├── manifest.json                      # 技能元數據
├── workflows/
│   ├── analyze.md                     # 完整背離分析工作流
│   ├── monitor.md                     # 持續監控工作流
│   └── cross-validate.md              # 交叉驗證工作流
├── references/
│   ├── data-sources.md                # ETF 庫存與價格資料來源
│   ├── methodology.md                 # 背離偵測方法論
│   └── input-schema.md                # 完整輸入參數定義
├── templates/
│   ├── output-json.md                 # JSON 輸出模板
│   └── output-markdown.md             # Markdown 報告模板
└── scripts/
    ├── divergence_detector.py         # 主偵測腳本
    ├── fetch_etf_holdings.py          # ETF 庫存抓取（Selenium）
    └── fetch_prices.py                # 價格數據抓取

</directory_structure>

<reference_index>

方法論: references/methodology.md

• 乖離の検出ロジック
• 二つの仮説による検証フレームワーク
• ストレススコアの計算

データソース: references/data-sources.md

• ETF公式サイトからの在庫取得（Selenium）
• Yahoo Financeの価格データ
• クロスチェック用データソース（COMEX、LBMA）

入力パラメーター: references/input-schema.md

• パラメーターの完全な定義
• デフォルト値と推奨範囲

</reference_index>

<workflows_index>

ワークフロー	目的	使用する場面
analyze.md	乖離の完全な分析	乖離の履歴を完全に分析する場合
monitor.md	状態の継続的な監視	日常の監視やアラート
cross-validate.md	乖離シグナルのクロスチェック	乖離の真偽を確認する場合
</workflows_index>

<templates_index>

テンプレート	目的
output-json.md	JSON出力構造の定義
output-markdown.md	Markdownレポートのテンプレート
</templates_index>

<scripts_index>

スクリプト	コマンド	目的
divergence_detector.py	--etf SLV --quick	乖離状態のクイックチェック
divergence_detector.py	--start DATE --end DATE --output FILE	過去データの完全な分析
visualize_divergence.py	--result result.json --output DIR	可視化レポートの生成
fetch_etf_holdings.py	--etf SLV --output holdings.csv	ETF在庫の取得
fetch_prices.py	--symbol SI=F --output prices.csv	商品価格の取得
</scripts_index>

<input_schema_summary>

主なパラメーター

| 參數 | 類型 | 預設值 | 說明 | |------------------------|--------|------------|----------------------------| | etf_ticker | string | (必填) | ETF/信託代碼（如 SLV） | | commodity_price_symbol | string | (必填) | 商品價格代碼（如 XAGUSD） | | start_date | string | 10Y 前 | 分析起始日 | | end_date | string | today | 分析結束日 |

背離參數

參數	類型	預設值	說明
divergence_window_days	int	180	背離計算視窗（天）
decade_low_window_days	int	3650	十年低點視窗（天）
min_price_return_pct	float	0.15	價格上漲門檻
min_inventory_drawdown_pct	float	0.10	庫存下滑門檻

完整參數定義見 references/input-schema.md。

</input_schema_summary>

<output_schema_summary>

{
  "skill": "monitor-etf-holdings-drawdown-risk",
  "asof": "2026-01-16",
  "inputs": {
    "etf_ticker": "SLV",
    "commodity_price_symbol": "XAGUSD"
  },
  "result": {
    "divergence": true,
    "price_return_window": 0.32,
    "inventory_change_window": -0.18,
    "inventory_decade_low": true,
    "inventory_to_price_ratio_z": -2.4,
    "stress_score_0_100": 78.5
  },
  "interpretations": [...],
  "next_checks": [...]
}

完整輸出結構見 templates/output-json.md。 </output_schema_summary>

<success_criteria> 執行成功時應產出：

• 背離狀態判定（divergence: true/false）
• 價格變化與庫存變化數值
• 十年低點判定
• 庫存/價格比值 Z 分數
• 壓力分數（0-100）
• 兩種對立假設解釋
• 下一步驗證建議清單 </success_criteria>