systematic-debugging

Systematic Debugging

Replace guess-and-check with an evidence loop that localizes where and why behavior diverges; test-driven-development implements the fix and incident-response owns live outages.

Workflow

1. Preserve evidence: Capture the exact error, stack trace, command, inputs, versions, environment differences, timing, and recent changes before touching anything.
2. Reproduce: Find the shortest reliable command or sequence; for intermittent failures record the frequency and vary one dimension at a time.
3. Reduce: Minimize input, fixture, process count, and component path while keeping the same failure, preferably as a focused test or disposable harness.
4. Localize: Trace bad state backward across calls, processes, network boundaries, configuration, and generated artifacts; at each boundary compare what entered with what left.
5. Find a working comparator: Locate the nearest known-good test, code path, version, environment, or commit and list every relevant difference before choosing one.
6. Form one hypothesis: State X causes the failure because Y evidence predicts Z observation and define a minimal probe that could falsify it.
7. Run the probe: Change one variable in a reversible fixture or add narrow instrumentation; record whether the prediction held and discard failed hypotheses instead of layering fixes.
8. Name the root cause: Explain the triggering condition, the faulty assumption or invariant, the propagation path, and why existing controls missed it; never blame timing, the environment, or a third party until that path and the missing resilience are understood.
9. Fix only when authorized: Write a failing regression test, implement the smallest root-cause fix, and verify the symptom plus the wider gate.
10. Report: Return symptom and impact, minimal reproduction, evidence and ruled-out hypotheses, root cause and propagation path, the authorized fix or recommended correction, regression proof, and residual uncertainty with the next probe.