plan-review

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: 修訂建議

四段審查完成後，輸出：

## 計畫審查摘要

| # | 維度 | 議題 | 決策 |
|---|------|------|------|
| 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 開始。