| name | debug |
| description | Use when the user reports a bug, asks to debug specific behavior, or when an unexpected failure occurs during execution. Applies the standing debugging protocol — reproduce, minimize, validate fix on a single job before scaling. |
Debug
Apply the standing debugging protocol when investigating reported bugs or unexpected failures.
When to use
- User says "debug X" or "X is broken"
- An execution loop hits an unexpected failure and needs structured root-cause analysis
- A test, experiment, or pipeline produces wrong output
When NOT to use
- The fix is obvious one-line correction (just apply it)
- The user wants exploration ("look at this and tell me what's happening") — that's investigation, not debug
References
kb/context/debugging-protocol.md — the canonical protocol (reproduce → minimize → validate single → scale; log format; anti-patterns)~/.claude/skills/systematic-debugging/SKILL.md (obra/superpowers) — 4-phase root-cause structure used within this protocol; consult for the formal Hypothesize → Test → Observe → Refine cycle and root-cause-tracing.md~/.claude/skills/verification-before-completion/SKILL.md (obra/superpowers) — evidence gating before declaring a fix complete
Steps
- Read
kb/context/debugging-protocol.md if not already in context
- Reproduce the failure with a minimal trigger; confirm before proposing any fix
- Minimize data size where applicable to shorten turnaround
- Form a hypothesis — write it down with predicted outcome
- Validate fix on a single job/instance before scaling to parallel
- Dispatch the actual code change to a
general-purpose subagent with a self-contained brief (per CLAUDE.md "Delegate Non-Trivial Editing")
- Log every attempt: hypothesis | action | outcome | next step
- If embedded in a milestone — append the log to the milestone file's Execution Log section
Output
- A reproduced bug → confirmed working fix → record in execution log
- Or escalation to user after 3 failed hypotheses with no clear next step
