Debug root cause
Use when a test fails, a bug appears, or behaviour is unexplained — find the root cause before changing code, instead of guessing at fixesFrom its SKILL.md
npx -y skills add fripig/superpower-lite --skill debug-root-causeAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
One thing to look at
- 0 stars0 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
SKILL.md
2.3 KB, as published. Nobody here has run it
Debug: Root Cause First
鐵律：先找到根因再改程式碼。症狀消失不等於問題解決。
失敗兩次以上還在猜，就代表你在試錯而不是除錯——停下來走這個流程。
階段一：找根因（不准改任何程式碼）
- 完整讀錯誤：整段 stack trace、實際 vs 預期、發生在哪一行。不要只看最後一行。
- 往上追到源頭：錯誤爆出來的地方通常不是壞掉的地方。壞值是哪來的？沿著呼叫鏈往上，直到找到「第一個產出錯誤值的地方」。
- 確認能穩定重現：偶發代表還有沒掌握的變因（時序、快取、測試互相污染、環境差異）。找到那個變因，它往往就是根因。
- 問三個問題：
- 這段程式碼為什麼當初這樣寫？（git log / blame 常有答案）
- 這是單一 bug，還是同一個模式在別處也錯？
- 環境/設定/資料的差異能解釋這個現象嗎？
根因的檢驗標準：你能說出「因為 A，所以 B，所以出現症狀 C」，而且能預測「改掉 A 之後 D 也會跟著變」。說不出這條因果鏈，就還沒找到根因。
階段二：驗證假設再修
- 寫出假設：「我認為根因是 X，因為 Y。」
- 先寫一個重現該症狀的測試（此時應該是紅的）——這同時驗證了你的假設。
- 修根因，不是修症狀。跑測試，紅轉綠。
- 確認沒有其他地方被影響（跑相關測試切片）。
反模式
| 你在做的事 | 為什麼是錯的 |
|---|---|
| 加 try/catch 讓錯誤不見 | 症狀消失，資料照樣壞 |
| 加 sleep / retry 讓時序問題不發生 | 沒解決競態，只是機率變低 |
| 改測試的斷言去配合實際輸出 | 你把測試改成測「現在的錯誤行為」 |
| 一次改好幾個地方看哪個有效 | 就算好了也不知道是哪個，而且多改的地方是新的債 |
| 「先加防禦性檢查再說」 | 沒有根因的防禦是亂槍打鳥 |
找不到根因時
老實說「追到 X 為止，再往下需要 Y（線上 log / 實際資料 / 重現環境）」，並列出你已排除的可能性。不要用一個沒把握的修正混過去。