diagnosing-bugs

For non-deterministic bugs, raise the reproduction rate instead of chasing a clean repro: loop the trigger 100 times, parallelize, add stress, narrow timing windows, or inject sleeps. A 50% flake rate is debuggable; keep increasing the rate until the failure is observable.

Build a tight 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 the scenario by removing inputs and steps one at a time until every remaining element is load-bearing.

For performance regressions, avoid log-based debugging. Establish a baseline measurement with a timing harness, performance.now(), a profiler, or a query plan, then bisect between known states. Measure first, fix second.

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.

Stop and say so explicitly, listing what you tried. Ask the user for environment access, a captured artifact such as a HAR file, log dump, or screen recording, or permission to add temporary production instrumentation. Do not hypothesize without a feedback loop.