# Research Workflow

**版本：** 1.0  
**用途：** 把研究從「想法」帶到「可驗證的 paper / live」的固定 stage-gate 流程。  
**原則：** 不跳關、不覆寫 baseline、不用 in-sample Sharpe 單獨選參數、沒有 paper 不進 live。

---

## 0. 流程總覽

```
A/ 發現
  01 定義問題與研究目標
  02 資料註冊與診斷
  03A 機制驅動發現
  03B 資料驅動發現

B/ 設計
  04 EDA 與預測
  05 模型配對與策略規格
  06 原始策略與初回測

C/ 選擇與時間驗證
  07 穩定參數區域
  08 策略狀態與過濾器
  09 時間順序樣本外驗證

D/ 驗證組合
  10 穩健性與執行能力
  G1 單策略審核卡
  11 Alpha 去重與組合配置
  12 Paper 部署與 OMS
  G2 組合風險與價值卡
  G3 執行一致性卡

E/ 組合驗證與擴張
  13 小資金 Live 與漸進擴張

F/ 實盤、監控與回顧
  14 持續績效與系統監控
  15 衰退診斷與回顧
```

每個研究在 `research.json` 記錄：

```json
{
  "stage": "10",
  "gate": "G1",
  "gate_status": "partial",
  "next_stage": "G1"
}
```

`gate_status`: `not-started` | `partial` | `passed` | `failed`.

---

## A/ 發現

### 01 定義問題與研究目標

- **目的：** 把直覺變成可證偽的問題。
- **必要輸入：** 市場結構觀察、交易對手假設、目標資產/頻率、成功定義。
- **產出：** `research.json`、`README.md`、Alpha hypothesis。
- **通過條件：**
  - 能說明「誰在對面交易、為什麼會虧」。
  - 有明確的失敗條件，而不只是「Sharpe 要高」。
- **對應指令：** `/strategy` 的 hypothesis 段。

### 02 資料註冊與診斷

- **目的：** 確認資料可用、乾淨、時點正確。
- **必要輸入：** 訊號/評價 topic、交易所、頻率、歷史起訖。
- **產出：** 資料字典、缺口/重複/OHLC 檢查、時區與暖機期記錄。
- **通過條件：**
  - 無未解釋的缺口或重複。
  - 訊號與執行資料的時點關係明確。
  - 暖機期與 lookback 足夠。
- **對應指令：** datasource proxy 查詢 + 資料完整性表。

### 03A 機制驅動發現

- **目的：** 從市場結構推導候選因子。
- **產出：** 市場結構 → proxy → 候選因子。
- **通過條件：** 每個因子都有經濟/行為機制，不只是統計相關。

### 03B 資料驅動發現

- **目的：** 從原始資料找可檢驗的因子組合。
- **產出：** 清洗後特徵、因子組合、探索性結果。
- **通過條件：** 沒有用未來資料；有記錄嘗試次數。

---

## B/ 設計

### 04 EDA 與預測

- **目的：** 先驗假設 → 如何預測、何時會失效。
- **產出：** 分布、rolling 統計、regime 圖、失效模式。
- **通過條件：** 知道策略在什麼市場狀態下會失效。

### 05 模型配對與策略規格

- **目的：** 把因子變成可執行的規則。
- **必要輸入：** 標的、進出場、部位 sizing、風控、費用、延遲。
- **產出：** `alpha.py`、參數表、執行假設。
- **通過條件：** 規格完整到另一個人可以重現。

### 06 原始策略與初回測

- **目的：** 先做出不含 regime/filter 的原始表現。
- **產出：** `report.parquet`、baseline summary、plots。
- **通過條件：**
  - 使用幾何權益曲線。
  - 無 look-ahead。
  - 交易帳本可重建。
- **對應指令：** `/strategy` + `/check-pipeline`。

---

## C/ 選擇與時間驗證

### 07 穩定參數區域

- **目的：** 找寬廣高原，不是單一最高點。
- **產出：** entry/exit grid、heatmap、plateau 分析、換手/成本。
- **通過條件：**
  - 參數鄰域不是懸崖。
  - 不用 in-sample Sharpe 單獨選參數。
  - 記錄所有嘗試（multiple testing）。

### 08 策略狀態與過濾器

- **目的：** 研究何時適合交易，與原始 Alpha 分層。
- **產出：** regime filter、vol targeting、ATR exit 等變體。
- **通過條件：** 過濾器有經濟理由，且不是只在 in-sample 有效。

### 09 時間順序樣本外驗證

- **目的：** 每個 fold 只用過去資訊，嚴格 OOS。
- **產出：** walk-forward、forward test、OOS 指標。
- **通過條件：**
  - 參數只在訓練期選。
  - OOS 不是 negative 或完全靠單一 regime。
  - 明確標記「已被觀察」與「真正未見」的資料。

---

## D/ 驗證組合

### 10 穩健性與執行能力

- **目的：** 多重試驗、因果路徑、成本與延遲分別測試。
- **產出：** bootstrap、block bootstrap、DSR、Reality Check、成本/延遲敏感度、paper smoke test。
- **通過條件：**
  - 會計可重建。
  - 成本/延遲不會把 edge 吃掉。
  - 統計不確定性有區間。

### G1 單策略審核卡

**這是進 portfolio / OMS 前的硬門檻。**

| 檢查 | 通過條件 |
|---|---|
| 會計 | PnL/equity 可精確重建；幾何 CAGR/MDD；無算術/幾何混用 |
| 交易帳本 | 淨往返交易、費用、勝率、PF 可重建 |
| 資料 | 缺口/時區/暖機期已記錄；無 look-ahead |
| OOS | walk-forward + 真正未見（若有）；不是只看 in-sample |
| 統計 | DSR / Reality Check 有報告；知道 multiple testing |
| 成本 | 費用、滑價、延遲敏感度 |
| 分級 | `pass` / `keep-in-research` / `reject`，並寫明理由 |

- **不通過：** 不能進 11/12。
- **對應指令：** `/research-dashboard` + G1 checklist。

### 11 Alpha 去重與組合配置

- **目的：** 用相關矩陣找互補，先以等權重作基準。
- **產出：** correlation matrix、portfolio backtest、risk contribution。
- **通過條件：**
  - 不是把同一個 alpha 複製多次。
  - 組合風險有分解（beta、vol、MDD）。
  - 先等權重，再考慮其他 allocator。
- **對應指令：** `/portfolio`。

### 12 Paper 部署與 OMS

- **目的：** 即時計算持倉，將目標權重轉為實際訂單。
- **產出：** `hooks.py`、`oms.py`、`config.json`、paper run、guard counters。
- **通過條件：**
  - paper smoke test：overshoot 0、invariant held、無 stuck order。
  - 會計與回測一致。
  - 憑證與 `.env` 正確隔離。
- **對應指令：** `/execution`、`/deploy`（paper）。

### G2 組合風險與價值卡

| 檢查 | 通過條件 |
|---|---|
| 組合指標 | Sharpe / MDD / Calmar / Ulcer / 最長水下 |
| 風險分解 | beta、per-asset、per-alpha 貢獻 |
| 分散 | 相關矩陣不是全部 1 |
| 容量 | 換手、成本、流動性可接受 |

### G3 執行一致性卡

| 檢查 | 通過條件 |
|---|---|
| Paper vs model | 追蹤誤差可解釋 |
| Order/fill | 成交、取消、amend 行為一致 |
| Guards | overshoot 0、invariant held |
| 成本 | 實際費用/滑價與假設一致 |

---

## E/ 組合驗證與擴張

### 13 小資金 Live 與漸進擴張

- **目的：** 驗證實際成交、容量與成本後，再評估加倉。
- **前置條件：** G1 + G2 + G3 全部通過，且 paper 期間達標。
- **通過條件：**
  - 小資金 live 與 paper 的差異可解釋。
  - 沒有 unexplained accounting drift。
  - 才可討論放大資金。

---

## F/ 實盤、監控與回顧

### 14 持續績效與系統監控

- **目的：** 同時監控 Alpha、Portfolio 和執行健康。
- **產出：** 每日/每週 dashboard、alerts、drawdown/rolling Sharpe、exposure、tracking error。
- **對應指令：** `/monitor`。

### 15 衰退診斷與回顧

- **目的：** 判斷原因、選擇修正、停用或重新研究。
- **產出：** 診斷報告、修正/停用決策、lessons。
- **通過條件：**
  - 區分「市場 regime 改變」「執行問題」「alpha 失效」。
  - 不因短期 drawdown 隨意改參數。

---

## 對應平台指令

| 階段 | 指令/檔案 |
|---|---|
| 01–06 | `/strategy`、`/check-pipeline` |
| 07–10 | 研究腳本、`/research-dashboard` |
| G1 | G1 checklist（本文件） |
| 11 | `/portfolio` |
| 12 | `/execution`、`/deploy`（paper） |
| G2/G3 | 本文件的 gate cards |
| 13 | 小資金 live（需明確批准） |
| 14 | `/monitor` |
| 15 | research review / lessons |

---

## 硬規則

1. **不能跳過 G1 直接進 11/12。**
2. **不能覆寫 baseline**；研究結果放 `brain/research/`。
3. **不能用 in-sample Sharpe 單獨選參數**；要 walk-forward + OOS + multiple testing。
4. **沒有 paper 不進 live**；live 需要另外的風險批准。
5. **所有指標用幾何權益曲線**；算術 total return / 算術 MDD 只能作審計對照。
6. **所有研究要登記在 `research.json`**，並在 dashboard 顯示 stage/gate。
