ddd-fixbug

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：根因調查

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. 寫預期行為測試

   • 根據「使用者預期行為」撰寫測試案例
   • 這個測試描述的是「修好之後應該怎樣」
   • 測試設計遵循「測試品質」標準：測行為不測實作字面，source-grep 字串斷言、寫死 fixture 數量等反模式一律禁止
   • 執行測試，確認現在會 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 不開 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 後結束。