diagnosing-bugs

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

Build a tight feedback loop first: a failing test, curl script, CLI invocation, or Playwright script that asserts the user's exact symptom and goes red on this bug. 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-good and known-bad states. Measure first, fix second.

Yes, use the human-in-the-loop bash template (scripts/hitl-loop.template.sh) as a last resort. It prompts the user through manual steps like signing in and clicking buttons, captures observations as KEY=VALUE output, and feeds them back to the agent for analysis.

Writing the regression test first proves the test actually catches the bug by watching it fail before the fix and pass after. Only do this at a correct seam that exercises the real bug pattern; if no correct seam exists, that architectural gap is itself a finding to report.

Do not proceed to hypotheses without a working feedback loop; guessing from code reading is the failure mode this process prevents. If you genuinely cannot build a loop, stop, list what you tried, and ask the user for environment access or a redacted captured artifact like a HAR file or log dump.