diagnosing-bugs

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

Build a tight feedback loop first: a failing test, curl script, CLI invocation with fixture input, headless browser script, or replayed captured trace that asserts the user's exact symptom. The loop must be deterministic, fast, and able to go red on this specific bug before any hypothesis work begins.

Stop and say so explicitly rather than guessing. Ask the user for access to the environment that reproduces it, a redacted captured artifact such as a HAR file or log dump, or permission to add temporary production instrumentation.

Writing the regression test first proves the test actually catches the bug: you watch it fail, apply the fix, then watch it pass. It also forces you to find a correct seam where the test exercises the real bug pattern as it occurs at the call site.

For performance regressions, avoid log-based probing. Establish a baseline measurement with a timing harness, profiler, or query plan, then bisect between known-good and known-bad states. Measure first, fix second.

Use a human-in-the-loop bash script only as a last resort when no automated loop is possible, such as UI flows requiring manual sign-in. The script structures the human's steps and captures their observations as parseable output for the agent.