ddd.fixbug

ddd.fixbug — Bug 修復

系統性診斷與修復 bug。參考 Superpowers systematic-debugging 方法論，強制四階段流程，禁止跳過根因分析直接猜修。

Main agent 直接修——bug fix 通常小且急，派工開銷不值得。這是唯一 main agent 直接寫 code 的 skill。

兩個入口

入口	情境	差異
Post-xreview	xreview 產出 findings，使用者確認要修	跳過 Phase 1（問題已定位），從 Phase 2 開始
獨立觸發	使用者回報 bug 或自行發現	完整四階段

---

Phase 1：根因調查（獨立觸發時）

Post-xreview 入口跳過此階段。

1. 釐清問題

   • 從使用者描述中理解症狀
   • 確認預期行為 vs 實際行為

2. 重現

   • 找到穩定的重現步驟
   • 若無法重現，用 Question Tool 向使用者確認環境與條件

3. 定位根因

   • 讀 error log / stack trace，追蹤資料流
   • 比對正常路徑與異常路徑的差異
   • 檢查近期相關變更（git log、git blame）
   • 產出一句話根因假設，直接進入下一階段
   • 卡住時才用 Question Tool 向使用者確認假設方向

Phase 2：模式分析

1. 比對異常 code 與正常運作的 code（同檔案或同模組的類似邏輯）
2. 識別所有受影響的位置（同一模式是否在其他地方重複出現）
3. 判斷影響範圍——只壞一處，還是同類 bug 散佈多處

Phase 3：假設驗證

1. 寫預期行為測試

   • 根據「使用者預期行為」撰寫測試案例
   • 這個測試描述的是「修好之後應該怎樣」
   • 執行測試，確認現在會 fail（Red state）
   • 若測試直接 pass，代表假設有誤，退回 Phase 1 重新分析

2. 最小改動修復

   • 只改必要的 code，不順便重構
   • 一次驗證一個假設

3. 驗證

   • 執行剛才的測試，確認 pass（Green state）
   • 執行完整測試 suite，確認沒有 regression

4. 失敗處理

   • 第一次修不好：重新檢視假設，調整修復策略
   • 第二次修不好：擴大調查範圍，考慮是否誤判根因
   • 第三次仍未果：暫停，向使用者報告已排除的假設與目前卡點

Phase 4：收尾

1. 更新文件

   • 產出或更新 works.md（三合一格式，見下方）
   • 若是 sprint 內的 bug，更新對應 sprint 的 works.md
   • 若是獨立 hotfix，在 docs/ 下建 <序號>-hotfix-<簡述>/works.md（序號接續既有 docs 編號）

2. 回報使用者

   • 展示修復內容與測試結果
   • 等待使用者確認後才 commit

---

三合一 works.md 格式

獨立 hotfix 不走 spec/tasks 流程，改用一份三合一的 works.md 記錄完整脈絡：

# Hotfix: <簡述>

## 問題描述
- **症狀**：<使用者觀察到的現象>
- **預期行為**：<應該怎樣>
- **影響範圍**：<哪些功能/使用者受影響>

## 根因分析
- **根因**：<一句話根因>
- **定位過程**：<怎麼找到的，排除了哪些假設>
- **受影響的檔案**：<列出修改的檔案>

## 修復內容
- **修了什麼**：<具體改動>
- **測試**：<新增或修改了哪些測試>
- **驗證結果**：<測試執行結果>

Post-xreview 的修復直接記在當前 sprint 的 works.md，不需要獨立開檔。格式簡化為一筆日誌紀錄：

### xreview 修正

- **[finding 摘要]**：<修了什麼> → <測試結果>
- **[finding 摘要]**：<修了什麼> → <測試結果>

---

核心限制

• 禁止跳過根因分析：不准「先試試看改這裡」。先分析再動手，卡住時才問使用者。
• 測試先行：修 code 前必須先有 failing test 描述預期行為。沒有 test 不准動 code。
• 最小改動：只修 bug，不順便重構、不加功能、不「改善」周圍的 code。
• 三振出局：連續 3 次修不好，強制暫停回報。禁止無限重試。
• 不改測試過關：修復階段禁止修改測試來讓它 pass。測試有誤就退回重寫測試。
• Commit 需授權：測試通過不等於提交授權，必須等使用者確認。

產出

• 修復後的程式碼 + 測試
• works.md（三合一或 sprint works.md 追加紀錄）
• Git commit（使用者確認後）

結束條件

修復完成、測試通過、使用者確認 commit 後結束。