systematic-debugging

name	systematic-debugging
description	Root-cause debugging — trace data flow, form hypotheses, verify the fix. Use when debugging failures, errors, or unexpected behaviour.
user-invocable	false

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

1. Reproduce — a failing case you can run on demand. Without this you cannot tell a fix from a coincidence.
2. Localize — narrow to the specific code producing the wrong value. Strategies in localization.md.
3. — state the mechanism: this input, through this path, yields this wrong output. Then predict what changing it will do.