diagnosing-bugs

For non-deterministic bugs, raise the reproduction rate instead of seeking a clean repro: loop the trigger 100 times, parallelize, add stress, and narrow timing windows. A 50% flake rate is debuggable; keep increasing the rate until the failure is reliable enough to instrument.

Build a feedback loop first: a failing test, curl script, CLI invocation, headless browser script, or replayed trace that goes red on the exact symptom. Then minimize by removing inputs and steps one at a time until every remaining element is load-bearing for the failure.

A bisection harness automates booting the system at a given state and checking for the bug, so you can run git bisect run against it. It is used when a bug appeared between two known commits, versions, or datasets.

Write the regression test before the fix, but only at a correct seam where the test exercises the real bug pattern as it occurs at the call site. If no correct seam exists, document that finding as an architectural issue rather than writing a shallow test.

For performance regressions, logs are usually the wrong tool. Instead establish a baseline measurement with a timing harness, profiler, or query plan, then bisect the regression. Measure first, fix second.

Stop and say so explicitly rather than hypothesizing without a loop. Ask the user for environment access, a captured artifact such as a HAR file or log dump, or permission to add temporary production instrumentation.