---
name: plan-review
description: |
  互動式計畫審查：在實作前檢視計畫的完整性、方向、風險與範圍。
  適用 codex-plan 產出、plan mode 計畫、或任何實作計畫文件。

  觸發詞：/plan-review、review plan、審查計畫、檢視計畫
user_invocable: true
argument_hint: "[plan file path] (optional, auto-detects codex-plan.md or latest .claude/plans/)"
---

# Plan Review

實作前的計畫審查。四個維度逐段檢視，每個議題給選項和建議，確認後才進下一段。

**定位**：審查計畫本身（任務拆解、方向、風險），不是 code review。程式碼層面的審查請用 `/code-review`。

---

## Step 0: 定位計畫 + 選擇深度

### 定位計畫

按優先順序尋找：

1. **ARGUMENTS 指定路徑** → 直接讀取
2. **`codex-plan.md`**（當前目錄）→ codex-plan 產出
3. **`.claude/plans/`** → 取最新的 `.md` 檔
4. 都找不到 → 用 AskUserQuestion 請使用者指定

讀取計畫後，摘要核心目標（1-2 句），確認審查對象正確。

### 讀取相關程式碼

計畫中提到的 Target Files / 修改檔案 → **全部讀取**。不看現有程式碼就無法判斷計畫是否合理。

### 選擇審查深度

用 AskUserQuestion 詢問：

- **深度審查**：每段最多 4 個議題，適合大型功能或架構變更
- **快速審查**：每段最多 1 個議題，適合小改動或時間有限

---

## Step 1-4: 四段審查

依序執行。每段完成後用 AskUserQuestion 確認決策，再進下一段。

### 第一段：完整性

計畫有沒有漏東西？

- 任務拆解是否足夠細——每個 task 能在一次 commit 內完成？
- 任務之間的依賴關係是否正確？有沒有循環依賴或順序錯誤？
- 是否遺漏必要步驟（DB migration、config 變更、環境變數、文件更新）？
- Mermaid 依賴圖（如有）是否反映實際依賴？

### 第二段：方向性

方向對不對？有沒有更好的做法？

- **現有程式碼是否已能解決問題？** 計畫提議建新 service / 新模組 / 新 migration 時，檢查現有程式碼是否已具備所需功能——只需串接或擷取即可。這是最高優先級的檢查：一個洞察就能把 4 個 phase 壓縮成 80 行改動。
- 選擇的架構模式是否適合問題規模？有沒有更簡單的替代方案？
- 技術選型是否合理？有沒有跟現有 codebase 的慣例衝突？
- 修改的檔案清單是否正確？有沒有漏掉該改的檔案，或改了不該改的？
- 提出的 API / 介面設計是否清晰且一致？

### 第三段：風險

哪裡可能出事？

- 哪些步驟風險最高？失敗的後果是什麼？
- 有沒有 rollback 策略？能不能漸進式部署（feature flag、canary）？
- 有沒有考慮向後相容？會不會破壞現有使用者或 API 消費者？
- 測試策略是否覆蓋關鍵路徑？有沒有遺漏的邊界案例？

### 第四段：範圍

範圍合理嗎？

- 是否超出原始需求？有沒有偷渡不必要的重構或功能？
- 是否工程不足？有沒有偷懶跳過該做的事（錯誤處理、輸入驗證、測試）？
- 任務粒度是否適當？太粗的 task 應拆開，太碎的可合併
- 估算的複雜度是否合理？有沒有被低估的部分？
- **計畫是否明確列出「NOT in scope」？** 如果沒有，主動建議補上——列出被排除的相關工作及排除理由。這能防止實作時 scope creep，往往比計畫本身更有價值。

---

## 議題呈現格式

每個議題必須包含：

1. **問題描述** — 具體指出計畫中的哪個 task/step，引用檔案路徑（如相關）
2. **選項** — 2-3 個選項（含「不處理」），每個標明：
   - 對計畫的影響（需改幾個 task？加減步驟？）
   - 風險變化（提高或降低？）
   - 實作成本變化
3. **建議** — 推薦的選項及理由

### 輸出範例

```
### 1. 完整性：缺少 DB migration 步驟

**問題**：Task 3 新增 `status` 欄位到 User model，但計畫沒有對應的
migration task。部署時會因為欄位不存在而失敗。

**選項**：
- **A) 在 Task 3 前插入 migration task**（建議）
  影響：+1 task，Task 3 加 blockedBy | 風險：降低 | 成本：低
- **B) 合併進 Task 3**
  影響：Task 3 變大 | 風險：不變 | 成本：零
- **C) 不處理**
  影響：無 | 風險：部署失敗 | 成本：零

**建議 A**：migration 獨立一個 task 方便 rollback，且不混淆程式碼變更。
```

### AskUserQuestion 格式

每段結束時用 AskUserQuestion：

- 選項標籤標示 **議題編號 + 選項字母**
- 建議選項放第一個
- 深度模式範例：`1A + 2B + 3A`
- 快速模式直接用選項字母

---

## Step 5: 修訂建議

四段審查完成後，輸出：

```markdown
## 計畫審查摘要

| # | 維度 | 議題 | 決策 |
|---|------|------|------|
| 1 | 完整性 | 缺少 DB migration | A: 插入獨立 task |
| 2 | 方向性 | 可用現有 middleware 取代自建 | A: 改用現有 |
| 3 | 風險 | 無 rollback 策略 | A: 加 feature flag |
| 4 | 範圍 | Task 7 偷渡重構 | B: 拆到獨立 PR |

### 建議修訂
- [ ] Task 2.5: 新增 migration for User.status（blocked by: Task 2）
- [ ] Task 4: 改用 existing authMiddleware，刪除自建邏輯
- [ ] Task 1: 加 feature flag ENABLE_NEW_AUTH
- [ ] Task 7: 移出計畫，另開重構 PR

### NOT in scope（建議補入計畫）
- **AuthService 重構** — 現行架構足夠，獨立 PR 處理
- **Email 驗證流程改版** — 與本次功能無關，避免牽動範圍
- **舊 API 版本淘汰** — 需協調下游消費者，不適合綁在一起
```

---

## 審查原則

- **完整但不囉嗦** — 漏步驟要補，但不要把簡單的事搞複雜
- **最簡單的正確方案** — 有更簡單的做法就提出來
- **風險意識** — 高風險步驟必須有 fallback
- **範圍紀律** — 不允許 scope creep，也不允許偷懶

---

## Now Execute

使用者的審查請求見下方 `ARGUMENTS:`。從 Step 0 開始。