diagnosing-bugs

Diagnosing Bugs

Find the cause of the reported symptom, fix it within the requested scope, and retain evidence that the fix works. Read relevant code and logs to construct a reproduction. Existing domain terms and ADRs constrain the diagnosis.

Establish the failure

Prefer an existing harness or test that reaches the affected behavior. Otherwise build the smallest practical test, CLI invocation, HTTP request, or browser scenario. Read the applicable entry in the harness reference before using a harness.

Run the reproduction before changing behavior. Capture the command, exit status, input, and observed symptom. An unrelated setup failure does not reproduce the bug. Reduce inputs when useful, retaining the original case.

For intermittent failures, record the observed rate and conditions. Use seeded inputs, bounded repetition, or targeted stress to improve the signal. For performance regressions, capture a comparable timing or profiler baseline before the fix. Avoid arbitrary repetition targets or latency requirements for the harness.

If the environment cannot reproduce the failure, continue useful code and log inspection and label hypotheses as unverified. Request only the missing artifact or access needed to establish the failure. Do not claim a reproduced or fixed bug without evidence, or add production instrumentation without authorization.

Test the cause

State a falsifiable hypothesis and the observation that would distinguish it from plausible alternatives. Use a debugger, targeted instrumentation, or bisection as appropriate. Change one relevant variable at a time and update the hypothesis from the result. Do not invent extra hypotheses to meet a quota.

Tag temporary instrumentation so it can be removed. Preserve unrelated edits when reverting an experiment.

Fix and verify

Retain the reproduction as a regression test or runnable fixture at a boundary that exercises the real failure. Observe it fail before the fix and pass after. Recheck the original scenario if the retained case was reduced.

If no suitable test boundary exists, explain the limitation and retain the best available reproduction. Do not substitute a test that cannot detect the symptom. Report necessary architectural follow-up without starting an unrelated refactor.

Remove temporary instrumentation and files created only for the experiment. Complete the mandatory post-change verification. Report the cause, changed behavior, and actual verification results. Stop when the requested fix and required checks are complete.