allyoushawn 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.mdif 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-purposesubagent 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