| name | debugging |
| description | Systematic root cause investigation before proposing fixes. Triggers: bugs, test failures, unexpected behavior, 'why is this failing', 'not working', 'broken'. |
Systematic Debugging
Fixing without understanding creates new bugs. Investigate first, fix second.
Phase 1: Investigate
- Read errors — stack traces, line numbers, exact messages
- Reproduce — exact steps. Intermittent? Log at component boundaries.
- Check recent changes —
git diff, new deps
- Trace data flow from symptom to source
Phase 2: Compare
- Find working examples in codebase
- Read reference implementation fully
- Diff all differences — deps, config, assumptions
Phase 3: Hypothesize + Test
- Form hypothesis: "X causes this because Y"
- Oracle test (when useful): Compare against known-good baseline — available worktree (
git worktree list, detached HEAD = available), reference impl, or reduced test case. Only create new worktrees for non-obvious multi-component bugs. Return to detached HEAD when done.
- 3+ plausible hypotheses → parallelize. Spawn one subagent per hypothesis (each traces one, reports evidence for/against). Sequential testing wastes cycles when each test is slow.
- Smallest possible change to test. One variable at a time.
- Confirmed → Phase 4. Refuted → new hypothesis (3rd+ → parallelize per step 3)
Dead end: 3 hypotheses all fail → re-enter Phase 1 with broader scope. Still stuck → escalate as architectural.
Phase 4: Fix
- Write failing test that reproduces the bug
- Single fix — one change
- Verify — test passes, no regressions
- Fix fails? < 3 attempts → Phase 1. >= 3 → architectural issue
3+ Fixes = Architectural Problem
Repeated patches without root cause understanding signal a design problem. Tactical fixes compound debt and mask the real issue.
STOP. Discuss with human before more fixes.
Red Flags → Back to Phase 1
- Proposing fixes before tracing data flow
- "It's probably X" without evidence
- Multiple changes at once (shotgun debugging)
- "Quick fix for now" / "Just try changing X"
- Skipping or deleting tests
