Debug

A bug is solved only when the original symptom is captured, the cause is supported by discriminating evidence, and the original scenario verifies the result.

Establish the signal

Read the relevant code, tests, project guidance, and available artifacts. Build the smallest practical feedback loop that distinguishes failure from success: a test, command, request, replay, trace, benchmark, or bounded manual check.

The signal should exercise the real path, be repeatable enough to guide decisions, and run cheaply enough to use after each meaningful change. For intermittent failures, measure a bounded reproduction rate. For performance regressions, record a baseline before changing code.

When the exact environment is unavailable, use the strongest available evidence at the nearest controllable boundary. State what remains unverified; do not turn static plausibility into proven root cause.

Isolate the cause

Reproduce or observe the symptom, then remove irrelevant inputs and steps. Form falsifiable explanations and run the cheapest probe that distinguishes them. Change one variable at a time.

Claim a root cause only when evidence connects the suspected condition to the observed failure. Prefer toggling the suspected condition or comparing known-good and failing states. Error suppression, retries, disabled features, and changed expectations are not causal proof by themselves.

State the cause plainly: what breaks, under which condition, and why that condition produces the symptom.