Systematic Debugging

No fix without a proven root cause. Guessed patches destroy the evidence and stack new failure modes on old ones; the loop below is faster than thrashing — for simple bugs and emergencies too.

The loop

1. Read the evidence. The full error text, the complete stack trace, the failing assertion, exact line numbers and error codes. Errors usually name their cause; do not skim past them.
2. Reproduce reliably. Exact steps, smallest input that still fails. No reliable repro means gather more data — never fix blind.
3. Diff against the last good state. Recent commits, dependency bumps, config and environment changes; git bisect when the breaking change is not obvious.
4. Locate before theorizing. When the failing path spans components (CI, build, signing; API, service, database), instrument each boundary — log what enters and what exits — run once, and let the evidence name the failing layer. When the error surfaces deep in a call stack, trace the bad value backward to its origin per references/tracing.md. The fix belongs at the source, not where the error appeared.
5. One hypothesis, one minimal change. State "X causes this because Y", change a single variable, verify. Refuted means a new hypothesis — never a second fix stacked on the first, and never several changes at once. Not knowing is a finding: say what is still unknown and instrument for it.
6. Fix with a regression test. Write the failing repro test first (test quality per writing-tests), apply the single root-cause fix, watch the test pass, confirm the suite stays green. No "while I'm here" changes riding along.

Escalation

Count failed fix attempts. At three, stop treating it as a code bug and question the design: symptoms recurring in different places mean the pattern is wrong, not the patch. Lay out the structural options instead of attempting fix number four.

Red flags — back to step 1