| name | ddd.fixbug |
| description | Bug 修復：四階段根因診斷與修復，main agent 直接修（不派 ddd-developer），產出三合一或 sprint works.md 紀錄。 獨立觸發的 hotfix 快速解時使用；xreview findings 的修正走 /ddd.xreview 流程，不用本 skill。 Trigger: "fix bug", "fix this", "bugfix", "hotfix", "修 bug", "修這個", "這裡壞了", "有 bug", /ddd.fixbug。
|
ddd.fixbug — Bug 修復
系統性診斷與修復 bug。強制四階段流程，禁止跳過根因分析直接猜修。
Main agent 直接修——bug 修復是探索性任務，需要與使用者即時討論假設與發現，且通常小而急，派工開銷不值得。這是唯一 main agent 直接寫 code 的 skill；例外只存在於本 skill，其他文件只引用本 skill，不重述條件。
定位：例外的快速解，與 /ddd.xreview 互斥。xreview findings 的修正屬於正式流程，由 /ddd.xreview 收集決策後派 ddd-developer 執行，不進入本 skill。
Phase 1：根因調查
-
釐清問題
- 從使用者描述中理解症狀
- 確認預期行為 vs 實際行為
-
重現
- 找到穩定的重現步驟
- 若無法重現，用 Question Tool 向使用者確認環境與條件
-
定位根因
- 讀 error log / stack trace，追蹤資料流
- 比對正常路徑與異常路徑的差異
- 檢查近期相關變更（
git log、git blame）
- 產出一句話根因假設，直接進入下一階段
- 卡住時才用 Question Tool 向使用者確認假設方向
Phase 2：模式分析
- 比對異常 code 與正常運作的 code（同檔案或同模組的類似邏輯）
- 識別所有受影響的位置（同一模式是否在其他地方重複出現）
- 判斷影響範圍——只壞一處，還是同類 bug 散佈多處
Phase 3：假設驗證
-
寫預期行為測試
- 根據「使用者預期行為」撰寫測試案例
- 這個測試描述的是「修好之後應該怎樣」
- 測試設計遵循「測試品質」標準：測行為不測實作字面，source-grep 字串斷言、寫死 fixture 數量等反模式一律禁止
- 執行測試，確認現在會 fail（Red state）
- 若測試直接 pass，代表假設有誤，退回 Phase 1 重新分析
-
最小改動修復
- 只改必要的 code，不順便重構
- 一次驗證一個假設
-
驗證
- 執行剛才的測試，確認 pass（Green state）
- 執行完整測試 suite，確認沒有 regression
-
失敗處理
- 第一次修不好：重新檢視假設，調整修復策略
- 第二次修不好：擴大調查範圍，考慮是否誤判根因
- 第三次仍未果：暫停，向使用者報告已排除的假設與目前卡點
Phase 4：收尾
-
更新文件
- 產出或更新 works.md（三合一格式，見下方）
- 若是 sprint 內的 bug，更新對應 sprint 的 works.md
- 若是獨立 hotfix，在
docs/ 下建 <序號>-hotfix-<簡述>/works.md（序號接續既有 docs 編號）
-
回報使用者
- 展示修復內容與測試結果
- 等待使用者確認後才 commit
三合一 works.md 格式
獨立 hotfix 不開 sprint 文件包，以一份三合一 works.md 承擔規格與紀錄：Phase 1 與使用者對齊預期行為與根因假設後才進入修復，這就是底線第 1 條（No Code Without Docs）的輕量規格確認形式。格式如下：
# Hotfix: <簡述>
## 問題描述
- **症狀**：<使用者觀察到的現象>
- **預期行為**：<應該怎樣>
- **影響範圍**：<哪些功能/使用者受影響>
## 根因分析
- **根因**：<一句話根因>
- **定位過程**：<怎麼找到的，排除了哪些假設>
- **受影響的檔案**：<列出修改的檔案>
## 修復內容
- **修了什麼**：<具體改動>
- **測試**：<新增或修改了哪些測試>
- **驗證結果**：<測試執行結果>
核心限制
- 禁止跳過根因分析：不准「先試試看改這裡」。先分析再動手，卡住時才問使用者。
- 測試先行：修 code 前必須先有 failing test 描述預期行為。沒有 test 不准動 code。
- 最小改動：只修 bug，不順便重構、不加功能、不「改善」周圍的 code。
- 三振出局：連續 3 次修不好，強制暫停回報。禁止無限重試。
- 不改測試過關：修復階段禁止修改測試來讓它 pass。測試有誤就退回重寫測試。
- Commit 需授權：測試通過不等於提交授權，必須等使用者確認。
產出
- 修復後的程式碼 + 測試
- works.md（三合一或 sprint works.md 追加紀錄）
- Git commit（使用者確認後）
結束條件
修復完成、測試通過、使用者確認 commit 後結束。
