Diagnose

The failure mode this prevents: guessing. Changing code before understanding the bug converts one bug into two. The loop is boring on purpose — each step gates the next.

The loop

1. Reproduce first. A bug you cannot trigger on demand cannot be fixed with confidence — only coincided with. Script the reproduction (a test, a curl, a driven flow), and record the exact failing observation: message, wrong value, timing.
2. Minimize. Shrink input, config, and code path until removing anything makes the bug vanish. The minimal reproduction usually names the culprit by itself.
3. One hypothesis at a time. State it falsifiably: "the claim races the cancel because the update isn't status-guarded". Say what evidence would kill it.
4. Instrument, don't mutate. Add logging/assertions to observe the hypothesis; do not change behavior yet. If the evidence kills the hypothesis, write down what you learned and form the next one — the discard pile is the map.
5. Fix the cause, not the symptom. If the observed error is downstream (a null here because a write was skipped there), keep walking up. Ask "what made this state possible?" until the answer is a decision, not a line.
6. Regression-test on the real reproduction (/tdd: red on the repro, then green). Then re-drive the original flow (/verify-live) to confirm the observed symptom — not just the test — is gone.
7. Leave a trace. One of:
   • a VOLATILE: tripwire, if the cause was an external fact that will drift again (provider limit, API quirk, framework behavior);
   • a CONTEXT.md invariant, if the cause was a violated assumption;
   • a one-line note in the fix commit body for everything else.

Rules

• Never claim a fix without having watched the reproduction fail before it and pass after it.
• Timebox hypothesis cycles; after three dead hypotheses, re-minimize — the reproduction is usually hiding a variable.
• Flaky ≠ unfixable: flakiness means time, ordering, or shared state is a hidden input. Make it explicit and the flake becomes deterministic.