| name | detect-us-equity-valuation-percentile-extreme |
| description | 把多個股票估值指標統一轉成在過去百年歷史中的分位數，再合成一個總分，判斷目前是否處於歷史極端高估區間，並用歷史類比（如 1929、1965、1999）給出風險解讀。 |
<essential_principles>
**分位數標準化核心**
將不同單位的估值指標（PE、PB、CAPE 等）統一成「0-100 的歷史分位數」：
- 分位數 = 100 × (歷史中 ≤ 當前值的樣本數 / 總樣本數)
- 例：CAPE 位於歷史第 98 分位 → 過去 130 年只有 2% 的時間比現在更貴
- 統一單位後，可跨指標合成「綜合估值分位數」
**多指標合成邏輯**
合成公式：composite_percentile = 加權平均(各指標分位數)
支援三種合成方式：
| 方式 | 公式 | 適用場景 |
|---|
| mean | 算術平均 | 各指標同等重要 |
| median | 中位數 | 抵抗單一指標異常拉升 |
| trimmed_mean | 去極端平均 | 穩健估計 |
重要：各指標可能有不同歷史長度，預設使用「各自歷史」計算分位數再合成。
**極端高估偵測邏輯**
if composite_percentile >= extreme_threshold (預設 95):
→ 判定「歷史極端高估」
→ 觸發風險解讀流程
歷史類比事件識別：
- 找出合成分位數超過門檻的峰值
- 用
episode_min_gap_days 去重（預設 10 年內只保留最高點）
- 輸出：1929、1965、1999、2021、當前...
**風險解讀框架**
「估值極端高」≠「明天崩盤」，但歷史特徵是：
- 風險分布不對稱：下跌尾巴變厚
- 未來中期報酬壓縮：估值均值回歸壓低長期報酬上限
- 波動先升後跌：事件後 6-12 月波動率通常上升
輸出事後統計：
- 未來 180/365/1095 天報酬分布
- 最大回撤中位數與尾部風險
- 波動率變化機率
**資料來源與限制揭露**
本 skill 使用公開替代資料，非彭博原始數據：
- Shiller CAPE: Robert Shiller 公開資料集（可回溯至 1871 年）
- 市值/GDP: FRED 公開數據（可回溯至 1950 年代）
- PE/PB/PS: 公開金融資料（歷史較短，約 30-50 年）
偵測美股估值是否處於歷史極端區間：
需要進行什麼操作？
| Response | Action |
|----------------------------------|----------------------------------------------|
| 1, "視覺化", "圖表", "chart" | 執行 `python scripts/visualize_valuation.py -o output` |
| 2, "快速", "quick", "check" | 執行 `python scripts/valuation_percentile.py --quick` |
| 3, "完整", "full", "analysis" | 閱讀 `workflows/execute-analysis.md` 並執行 |
| 4, "歷史", "類比", "episodes" | 閱讀 `workflows/historical-episodes.md` 並執行 |
| 5, "學習", "方法論", "why" | 閱讀 `references/methodology.md` |
| 6, "自訂", "custom", 提供參數 | 閱讀 `workflows/execute-analysis.md` 並使用參數執行 |
