diagnosing-bugs

Non-deterministic bugs are handled by raising the reproduction rate rather than seeking a clean repro: loop the trigger 100 times, run in parallel, add stress, narrow timing windows, or inject sleeps. A 50% reproduction rate is debuggable; 1% is not.

Performance regressions use a dedicated branch of the workflow: establish baseline measurements first with timing fixtures, performance.now(), profilers, or query plans, then bisect. Logging is usually the wrong tool for performance issues; measure before fixing.

Stop and state it explicitly, listing the methods attempted. Request reproducible environment access, sanitized captures such as HAR files or log dumps, or permission to add temporary production instrumentation. Proposing hypotheses without a feedback loop is forbidden.

A tight pass/fail signal that goes red on the exact symptom is the foundation of the method; bisection, hypothesis testing, and instrumentation all consume that signal. Building hypotheses from reading code alone is the failure mode this discipline prevents.

Yes, as a last resort the hitl-loop.template.sh script structures human-in-the-loop reproduction. The agent runs the script, the user follows prompted steps in their terminal, and captured observations are printed back as KEY=VALUE pairs for the agent to parse.

Every debug log line is tagged with a unique prefix like [DEBUG-a4f2] during instrumentation. Before completion, a single grep for that prefix confirms all instrumentation is removed, along with one-off prototypes, and the confirmed hypothesis is recorded in the commit message.