bug-investigationlisted

# Bug Investigation Skill ## 概述 一套系統化方法，用於調查複雜程式碼中的錯誤與異常行為。此技能包含五個階段： 1. **問題釐清** - 理解回報的問題與影響範圍 2. **證據蒐集** - 從資料庫與日誌收集可驗證的證據 3. **根因分析** - 追蹤資料流找出來源與分歧點 4. **修正方案設計** - 提出與評估解決方案並形成決策依據 5. **知識文件化** - 留存可重用的知識與調查結果 ## When NOT to Use - 已確認問題成因且使用者只要求直接實作小型修正 - 任務是一般 code review / doc review，沒有 root cause 調查需求 - 純新功能開發且沒有異常行為、資料不一致或測試回歸跡象 ## 核心鐵律 ``` 未完成 Phase 1-3（尤其 Phase 3），不得提出修正方案或修改程式碼。 ``` **強制要求**： - 所有五個階段必須完成，不可跳過。若受阻，必須記錄原因、缺口與下一步，並在調查文件中標示未完成狀態。 - 未完成 Phase 1-3 前禁止提出修正方案或改動程式碼。 - 所有輸出文件與報告以正體中文為主；保留原始 log、程式碼與欄位名稱。 ## Output - `docs/knowledge/[feature-name]/investigation.md`（問題定義、證據、根因） - `docs/knowledge/[feature-name]/solution-proposal.md`（方案比較、風險、推薦） - 必要時補齊 `data-flow.md`、`key-functions.md`、`related-tables.md` - 一段可執行的 next actions（進 OpenSpec / 補證據 / 停損） ## Verification - [ ] Phase 1-3 證據鏈完整且可追溯 - [ ] 根因有單一假設與最小驗證結果 - [ ] Phase 4 至少提供 2 個方案與 1 個推薦方案 - [ ] 已定義後續步驟（OpenSpec 或回到前一 Phase） ## 參考 - `references/scripts.md`：工具安裝與腳本使用說明 - `references/examples.md`：調查案例與寫作模板 - `references/root-cause-tracing.md`：根因回溯追蹤技巧 - `references/defense-in-depth.md`：多層防護驗證模式 - `references/condition-based-waiting.md`：以條件為基準的等待（解決 flaky 測試） - `references/wait-for-helper.ts`：條件等待 helper 範本（可直接複製） - `references/phase-templates.md`：各 Phase 文件與 SQL/表格模板 - `references/checklists.md`：完整檢查清單 - `scripts/find-polluter.sh`：定位污染測試與共享狀態問題（詳見 `references/scripts.md`） --- ## Phase 1: 問題釐清 > 提示：首次使用先執行 `./scripts/check-tools.sh`（詳見 `references/scripts.md`）。 ### 1.1 收集初始資訊 向使用者詢問以下資訊