obra/superpowers · skills/systematic-debugging/SKILL.md
systematic-debugging
“Systematic debugging: a strict root-cause-first process that stops the agent guessing at fixes. Solid.”
What it does
A four-phase debugging discipline: investigate the root cause, compare against working code, test one hypothesis at a time, then fix with a failing test first. After three failed fixes, it makes the agent stop and question the design with you.
- When the agent uses it
- On any bug, test failure, build break or unexpected behavior, before the agent proposes a fix.
- Who it is for
- For anyone whose agent flails through guess-and-check fixes. Skip it if you want fast patches over process, or don't use the companion superpowers skills.
- What it costs
- 211 lines, about 2.6k tokens once the agent loads it.
Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes
What it tells the agent to do
- Read errors and stack traces fully, reproduce the bug reliably, and check recent changes
- In multi-component systems, log data at each boundary to find which layer breaks
- Find similar working code and list every difference from the broken code
- State one hypothesis and test it with the smallest possible change
- Write a failing test, apply one fix at the root cause, and verify that all tests pass
- If 3 or more fixes fail, stop and discuss the architecture with the human before trying again
Lines worth reading
Straight from the file, with why each one matters.
line 17NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
The whole skill in one line, set in a code block so the agent can't skim past it.
line 195If ≥ 3: STOP and question the architecture (step 5 below)
A hard stop on fix-thrashing. Three strikes and the agent must talk design with you instead of trying fix #4.
line 236Is that not happening?" - You assumed without verifying
It teaches the agent to read your irritated questions as signals it went wrong. Uncomfortably accurate.
line 231**If 3+ fixes failed:** Question the architecture (see Phase 4.5)
There is no Phase 4.5. It means step 5 of Phase 4. A small slip in an otherwise tidy process.
line 27595% of "no root cause" cases are incomplete investigation.
A made-up statistic, but it does the job: it keeps 'it's just flaky' from being an easy exit.
Watch out for
- Low
Logging all data at component boundaries can print secrets or tokens into CI logs. The example avoids this, but the general rule doesn't warn about it.
line 77Log what data enters component
The scorecard
- TriggerSays when to use it7/10
Clear about when to use it (bug, test failure) but never says what it does.
- FocusOne clear job9/10
One job: debug by finding the root cause first. Tight throughout.
- LeanLight to load7/10
About 280 lines, but the red flags and excuses tables repeat the phases.
- ConcreteSteps you can follow7/10
Ordered phases, a bash example and a 3-fix rule. Much else is advice models already know.
- SafeSafe to run9/10
Diagnostic only. No destructive commands, network calls or hijack attempts.
What it does well
- The 3-failed-fixes rule hands control back to the human at exactly the point where agents usually spiral.
- The multi-layer signing example checks that a secret is SET or UNSET without printing its value.
- Each phase has a success test in the quick-reference table, so the agent knows when to move on.
How it could be better
Say what the skill does in the description
The description only says when to use it. Naming the method helps the agent match requests like 'find the root cause'.
Adddescription: Four-phase root-cause debugging: investigate, compare with working code, test one hypothesis, fix with a failing test. Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes
Ship the reference files it links, or drop the links
It points to root-cause-tracing.md and two other files, but none could be found next to it, so the agent may look for files that aren't there.
Add- **`root-cause-tracing.md`** - <one-line summary> (file: <path>)
Fix the 'Phase 4.5' reference
No Phase 4.5 exists, which can confuse an agent looking for the step.
Add**If 3+ fixes failed:** Question the architecture (see Phase 4, step 5)
Warn against logging secret values
The boundary-logging rule could leak credentials into logs on CI systems.
Add- Log what data enters component (redact secrets: print SET/UNSET, never values)
Kin reviews against Anthropic’s Extend Claude with skills and agentskills.io’s the Agent Skills standard. It reads SKILL.md only, so a script beside it can still do things the file does not say.