| name | forecast-sector-relative-return-from-yield-spread |
| description | 用美債殖利率曲線利差（如 2Y-10Y）建立「領先關係」，推估未來一段時間內成長股（Nasdaq 100）相對防禦股（Healthcare/XLV）的相對績效方向與幅度。 |
<essential_principles>
**領先落後關係定義**
美國公債利差（Yield Spread）作為領先指標：
spread_t = short_yield_t - long_yield_t
= US02Y_t - US10Y_t
spread 越高：短端相對更高（曲線更倒掛/更緊）
spread 越低（或從負回到 0、轉正）：曲線「回正/變陡」
此 spread 被認為領先反映：
- 經濟週期預期（倒掛 → 衰退預期）
- 風險偏好轉換（曲線變陡 → 風險偏好回升）
**相對報酬定義**
相對強弱比率（Ratio）：
ratio_t = risk_asset_t / defensive_asset_t
= QQQ_t / XLV_t
ratio 上升：成長股（Nasdaq）相對更強
ratio 下降：防禦股（Healthcare）相對更強（XLV 跑贏）
預測目標為「未來 H 個月的對數相對報酬」：
future_rel_return = log(ratio(t+H) / ratio(t))
正值 → Nasdaq 跑贏，負值 → XLV 跑贏
**「2 Years in Advance」的真正含義**
圖表的時間對齊邏輯：
- 把 spread 往前平移 lead_months 個月
- 目標是檢查：spread(t) 是否能解釋 ratio(t + H)
工程化寫法：
X = spread(t)
Y = future_rel_return(t, H) = log(ratio(t+H) / ratio(t))
然後做相關性/迴歸/交叉相關掃描來找「最佳領先期」。
避免直接用 ratio 水平做迴歸（有趨勢/非平穩問題），改用對數報酬。
**領先關係驗證框架**
需回答三件事：
-
是否真的存在穩定領先關係？
- 掃描多個 lead（6, 12, 18, 24, 30 個月）
- 看哪個 lead 下 corr(spread, future_rel_return) 最穩、顯著
- 跨子樣本驗證（前半段 vs 後半段）
-
目前情境對應的預測方向
- 最近 spread 水準、變化率
- 模型預測 E[future_rel_return]
- 分位數區間（如 80% 信心區間）
-
把預測翻譯成直覺語句
- 由 future_rel_return 轉回百分比：
**數據對齊原則**
實作「美國公債利差 → 板塊相對報酬」領先關係分析：
需要進行什麼操作？
| Response | Action |
|--------------------------------|------------------------------------------------------------------------|
| 1, "快速", "quick", "分析" | 執行 `python scripts/spread_forecaster.py --quick` |
| 2, "完整", "full", "自訂" | 閱讀 `workflows/analyze.md` 並執行 |
| 3, "掃描", "scan", "領先" | 閱讀 `workflows/analyze.md` 並聚焦 lead_scan |
| 4, "圖表", "chart", "視覺化" | 執行 `python scripts/plot_bloomberg_style.py --quick --output output/` |
| 5, "驗證", "穩定", "stability" | 閱讀 `workflows/analyze.md` 並聚焦穩定性驗證 |
| 6, "學習", "方法論", "why" | 閱讀 `references/methodology.md` |
| 提供參數 (如 ticker, lead) | 閱讀 `workflows/analyze.md` 並使用參數執行 |
