Systematic Debugging

Run this as the implementer. Send an explorer when you cannot find where a behaviour lives or what a locked dependency really does.

No fix without a reproduction, evidence, and a tested root cause. Do not edit production code while guessing. Guards, retries, delays, and several speculative changes at once are guessing.

1. Reproduce

1. State the expected and the observed behaviour exactly.
2. Reproduce with the smallest reliable command. Record inputs, command, output, and how often it happens.
3. Read the full error, stack trace, and nearby logs.
4. Trace the bad value back to where it first goes wrong, not where it shows. At a boundary - process, service, database, queue - check both sides.

If it will not reproduce, add a temporary diagnostic and read it back. Do not fix a theory.

2. Compare

Find the closest working example in the project and list every difference - configuration, inputs, lifecycle order, state, transaction boundaries, timing. Use it to locate one causal difference.

Common hiding places: side effects in callbacks, work enqueued inside an open transaction, a query returning empty instead of nothing, repeated per-item queries, an input filter dropping a key, an unapplied migration, a cache that outlives its data.

3. Test one hypothesis

1. Write it down: "The cause is X, because evidence Y predicts Z."
2. Run the smallest experiment that changes one variable.
3. If it is disproved, revert the experiment and form a new hypothesis. Never stack changes.

After three failed hypotheses, stop. Present the evidence and question the design or the assumptions with the user.

4. Fix through a failing test

• Unplanned bug: the diagnosis is evidence for a plan, not permission to edit. Go through brainstorming and an approved plan, then fix it as a unit.
• Inside an approved unit: continue.

Under test-driven-development: write a test that reproduces the root cause and watch it fail, make the smallest causal fix, remove temporary diagnostics, then run the full specs and lint once and re-run the original reproduction. Fix the source of the bad state, not only the symptom.

Review findings are evidence, not orders

Reproduce a behavioural finding before you fix it. Check a quality finding against the code and the project's rules. If fresh output shows a finding is wrong, report it rejected with that output. A wrong fix is worse than the finding.

Done when

The failure reproduced (or the limit is recorded), evidence supports the root cause, a regression test failed before the fix and passes after, the final specs and lint run passed, and the report explains why the fix addresses the cause.