指令用途
/diagnosing-bugs 將最佳除錯實踐包裝成一個紀律化的迴圈，階段逐階段把關。它適用於棘手的 bug 與效能回歸 —— 那些不能用一眼看完就修掉的問題。
它的迴圈是：
- 建立反饋迴圈 —— 讓它能命中這個 bug
- 最小化 —— 把迴圈縮到最小可重現
- 提出假設 —— 寫下你認為的根因
- 插樁 —— 加觀測點驗證假設
- 修復 —— 改程式碼
- 回歸測試 —— 確保修復有效且不破壞其他東西
每一階段都是一個把關點：不跳階、不猜測式亂改。這把除錯從「碰運氣」變成可重現的工程。
證據與 secret redaction
這個 skill 會要求顯示 commands、outputs 與擷取的 artifacts，因此每次顯示前都要先遮蔽 secret：把密鑰、token、cookie、authorization header 等內容替換成 <REDACTED>，並讓 feedback loop 透過 environment variables 取得憑證，避免把真正的值貼進命令或輸出。
對 HAR、log dump、core dump、screen recording 等 captured artifact，只引用能支撐診斷的訊號行，不要整份貼出可能含有 authentication header 的內容。如果 redacted output 仍不足以判斷根因，應明確說明不足，並向使用者索取更完整但同樣已 redacted 的 artifact。
Phase 1 的完成條件也包含：命名一個已實際執行過的 red-capable command，並展示已 redacted 的 invocation 與 output。使用 scripts/hitl-loop.template.sh 時，capture 會把擷取值印回 terminal，因此只用它記錄觀察結果；登入或輸入憑證應留在 step，不可捕獲或回顯 secret。
運作流程（階段把關）
- 建立反饋迴圈：先寫一個會命中 bug 的測試或重現步驟。沒有反饋迴圈，就是在飛盲。
- 最小化：移除一切與 bug 無關的東西，讓重現越小越好。最小重現 = 最快定位。
- 提出假設：明確寫下你認為的根因 —— 一句話、可證偽。
- 插樁：加 log / 觀測點來驗證假設。讓證據說話，而非直覺。
- 修復：根據已驗證的根因修改程式碼（一個假設對應一個修復）。
- 回歸測試：確認修復有效、bug 不再出現，且沒有引入新問題。
實戰對話範例
範例一：間歇性 API 慢
-
You:
我們的 API 偶爾會慢個 5 秒，找不到原因。
-
AI:
進入診斷迴圈。
階段 1 — 建立反饋迴圈：先寫一個腳本連打這個 endpoint 100 次，記錄每次延遲。確認能穩定重現「慢」的狀況。
跑完告訴我分佈 —— 多少次慢、慢多久、有沒有規律。
-
You:
100 次裡有 7 次超過 5 秒，其餘都在 200ms 內。慢的集中在每分鐘整點附近。
-
AI:
階段 2 — 最小化：每隔 10 秒打一次固定一個 query，觀察是否仍在整點附近變慢。
階段 3 — 假設：根據「整點規律」，我的假設是 —— 有某個排程任務（cron / 定時 GC / 背景同步）在整點搶資源。
-
You:
確實只在固定 endpoint 變慢，其他 endpoint 不受影響。
-
AI:
階段 4 — 插樁：在那個 endpoint 的程式碼加計時，特別是 DB query 與任何 cache 呼叫。並查整點前後的 process / cron。
把插樁數據給我，我們驗證假設。
範例二：測試偶爾失敗（flaky test）
- You:
有一個測試在我電腦都過，CI 偶爾 fail。
- AI:
階段 1：在 CI 跑 50 次同一支測試，看失敗率。
flaky test 的根因通常是隱藏的測試順序依賴或時序競爭。先量化再說。
為什麼要階段把關
常見的除錯反模式是把這些步驟跳著做：
- 跳過反饋迴圈直接猜：沒有重現就改，改了都不知道好沒好。
- 不最小化就插樁：在龐大系統裡亂加 log，訊號淹沒在噪音裡。
- 多個假設一起改：改了五處，不確定是哪一處真正修好的。
階段把關強制你：先有反饋迴圈、再最小化、再寫下一個假設、再插樁驗證、最後才改一處。
何時應該使用
- 棘手、間歇性、難以重現的 bug。
- 效能回歸（變慢、吃記憶體、卡住）。
- flaky test（時好時壞）。
- 改了「應該」有效卻沒效的情況。
何時不應該使用
- 一眼可見的 typo / 明顯錯誤：直接修，不值得跑完整迴圈。
- 緊急修復：先讓系統恢復，事後再用本 skill 做根因分析。
- 「如何」實作而非「為什麼壞」的問題：用
/tdd實作新功能。
與其他技能的關係
/diagnosing-bugs 是一個隨時可用的獨立技能，與 /prototype 互為鏡像 —— 兩者都建立反饋迴圈，但 /prototype 是前瞻的設計驗證，/diagnosing-bugs 是回溯的根因定位。不確定該用哪個 skill 時，用 /ask-matt 來路由。