Systematic Debugging
One entry point for finding why code is wrong. Read the section you need; each
links to a sibling file with the full detail.
The rule
No fix without a root cause. If you cannot say which line produces the wrong
value and why, you are guessing. A guess that happens to work is a latent bug —
it will come back wearing different symptoms.
Red flags that you have skipped the diagnosis: changing code to "see if it
helps", adding defensive checks around a symptom, fixing the same area twice,
or being unable to explain why the fix works.
Pick a depth
| Situation |
Do this |
| Obvious cause, one file, low risk |
Fix inline. No ceremony. |
| Needs investigation, unclear origin |
Follow workflow.md |
| Production-critical, intermittent, or uncertain |
Run /dev:fix — full TDD with review gates |
/dev:debug routes between these three for you.
The four phases
- Reproduce — a failing case you can run on demand. Without this you cannot
tell a fix from a coincidence.
- Localize — narrow to the specific code producing the wrong value.
Strategies in
localization.md.
- Explain — state the mechanism: this input, through this path, yields this
wrong output. Then predict what changing it will do.
- Verify — the reproduction now passes, and you can say why. Re-run the
surrounding tests; a fix that breaks a neighbour was the wrong fix.
Full walkthrough with output schemas: workflow.md.
Reference files
| File |
Contents |
method.md |
Principles, red flags, hypothesis discipline, strategies by problem type (performance, intermittent, regression, integration) |
workflow.md |
The phase-by-phase standard workflow with report schemas |
localization.md |
Three fault-localization strategies — stack-trace grep, BM25 keyword search, AST context expansion — plus context-budget rules and the large-codebase path |
session-setup.md |
Session directory layout, stack detection, reproduction capture, bug-report schema. Shared by /dev:debug and /dev:fix. |
references/techniques.md |
The technique catalogue — stack-trace reading, error categories, wolf fence, data-flow tracing, logging, breakpoints, plus browser and Node.js specifics |
Read references/techniques.md in the Localize phase, when you know which phase you
are in and need the concrete move. It is a catalogue, not a method — reading it first
invites picking a technique before you have a hypothesis.
Related
dev:browser-debugging — anything involving a browser, console, or network tabdev:test-driven-development — writing the failing test that pins the bug
1---2name: systematic-debugging-23description: Root-cause debugging — reproduce, localize, explain, verify — with depth routing and a technique catalogue for stack traces, wolf fence and data-flow tracing. Use when anything errors, crashes or misbehaves, even on a bare pasted trace.4---56# Systematic Debugging78One entry point for finding why code is wrong. Read the section you need; each9links to a sibling file with the full detail.1011## The rule1213**No fix without a root cause.** If you cannot say which line produces the wrong14value and why, you are guessing. A guess that happens to work is a latent bug —15it will come back wearing different symptoms.1617Red flags that you have skipped the diagnosis: changing code to "see if it18helps", adding defensive checks around a symptom, fixing the same area twice,19or being unable to explain why the fix works.2021## Pick a depth2223| Situation | Do this |24|---|---|25| Obvious cause, one file, low risk | Fix inline. No ceremony. |26| Needs investigation, unclear origin | Follow `workflow.md` |27| Production-critical, intermittent, or uncertain | Run `/dev:fix` — full TDD with review gates |2829`/dev:debug` routes between these three for you.3031## The four phases32331. **Reproduce** — a failing case you can run on demand. Without this you cannot34 tell a fix from a coincidence.352. **Localize** — narrow to the specific code producing the wrong value.36 Strategies in `localization.md`.373. **Explain** — state the mechanism: this input, through this path, yields this38 wrong output. Then predict what changing it will do.394. **Verify** — the reproduction now passes, and you can say why. Re-run the40 surrounding tests; a fix that breaks a neighbour was the wrong fix.4142Full walkthrough with output schemas: `workflow.md`.4344## Reference files4546| File | Contents |47|---|---|48| `method.md` | Principles, red flags, hypothesis discipline, strategies by problem type (performance, intermittent, regression, integration) |49| `workflow.md` | The phase-by-phase standard workflow with report schemas |50| `localization.md` | Three fault-localization strategies — stack-trace grep, BM25 keyword search, AST context expansion — plus context-budget rules and the large-codebase path |51| `session-setup.md` | Session directory layout, stack detection, reproduction capture, bug-report schema. Shared by `/dev:debug` and `/dev:fix`. |52| `references/techniques.md` | The technique catalogue — stack-trace reading, error categories, wolf fence, data-flow tracing, logging, breakpoints, plus browser and Node.js specifics |5354**Read `references/techniques.md` in the Localize phase**, when you know which phase you55are in and need the concrete move. It is a catalogue, not a method — reading it first56invites picking a technique before you have a hypothesis.5758## Related5960- `dev:browser-debugging` — anything involving a browser, console, or network tab61- `dev:test-driven-development` — writing the failing test that pins the bug
MadAppGang