| name | debugging |
| description | Structured debugging workflow: reproduce, localize, reduce, fix, guard. USE FOR: test failures, build breaks, unexpected behavior, runtime errors. Use when quality gates fail, a bug is reported, or behavior does not match expectations. NOT FOR: writing new features test-first (test-driven-development), or reviewing code that already works (reviewing-code). |
Debugging — 5-Step Triage
Resist the urge to guess — follow the steps in order.
The 5 Steps
Step 1 — Reproduce
Reproduce the failure reliably before doing anything else. If you cannot reproduce, check environment differences, leftover state, or timing dependencies.
- Exit: You can trigger the failure on demand.
Step 2 — Localize
Narrow where the failure originates. Bisect — do not read the entire codebase.
Pick the isolation technique that fits the situation:
| Technique | How | When to use |
|---|
| Binary search | Comment out or bypass half the code path, check if failure persists, repeat | Large codebase, unclear location |
| Input reduction | Simplify the input until the bug disappears, then add back the trigger | Complex inputs, data-dependent bugs |
| Dependency elimination | Mock or remove external deps one at a time | Could be in a dependency or integration |
| Version bisect | git bisect to find the commit that introduced the regression | Known-good prior state exists |
| Targeted logging | Add log statements at function entry/exit boundaries (not everywhere) | Need to trace runtime execution flow |
For unfamiliar code, use the Explore subagent to map module boundaries before diving in.
- Exit: You know which file, function, and roughly which lines cause the failure.
Step 3 — Reduce
Create the simplest possible reproduction. Skip if the reproduction is already trivial.
- Exit: A minimal test case or snippet that demonstrates the bug clearly.
Step 4 — Fix
Fix the root cause, not the symptom.
- Fix at the source — no workarounds downstream.
- Smallest correct change — do not bundle refactors with bug fixes.
- Exit: Reproduction passes. Full test suite passes. Root cause addressed.
Step 5 — Guard
Prevent recurrence.
- Write a regression test that fails without the fix and passes with it.
- Commit the fix and guard together.
- Exit: A test guards against recurrence.
Common Rationalizations
| Rationalization | Reality |
|---|
| "I know what the bug is, let me just fix it" | Skipping reproduction means you might fix the wrong thing. |
| "It works on my machine" | Environment differences are bugs too. |
| "I'll just restart and try again" | Intermittent failures are real bugs — harder to find, not less important. |
Red Flags
- Fixing without reproducing first
- Multiple "fix" attempts without localizing the root cause
- Bug fix committed without a regression test
See Also
reviewing-code — when debugging uncovers code quality issues for review~/.ai-shared/references/testing-patterns.md — for writing effective regression tests~/.ai-shared/references/cognitive-debt.md — when the bug is in agent-generated code you never read; run the walkthrough workflow before trying to localize
