Diagnose, don't fix. The deliverable is a root-cause finding with evidence — apply a fix only if the user then asks.
Steps
- Pin down the report. Extract from the report (ask only for what's
missing and blocking): observed behavior, expected behavior, steps or
input that trigger it, environment/version if relevant.
- Completion criterion: you can state "given X, it does Y, but should do Z" in one sentence.
-
Reproduce — or trace when you can't. Prefer an actual reproduction (run the failing command, a minimal script, or an existing test tightened to the case). When reproduction isn't feasible (needs external services, prod-only data), trace the code path statically from the entry point the report implies, and say the diagnosis is trace-based.
- Completion criterion: the failure is observed firsthand, or the full
path from trigger to symptom is traced with
file:linehops.
- Completion criterion: the failure is observed firsthand, or the full
path from trigger to symptom is traced with
-
Isolate the root cause. Follow the data from symptom back to the first point where state or logic diverges from intent. Distinguish the root cause from where the error surfaces — they are usually different lines. Check
git log/git blameon the suspect code: a recent change that introduced it is strong corroborating evidence.- Completion criterion: one specific location (
file:line) and mechanism explains every symptom in the report. A cause that explains only some symptoms is a co-incident finding, not the root cause — keep digging or report the gap explicitly.
- Completion criterion: one specific location (
-
Assess blast radius. Find other callers/inputs that hit the same defect (Grep for the pattern, referencing symbols). Note data that may already be corrupted if the bug writes state.
- Completion criterion: every caller of the defective code is classified affected / unaffected.
-
Propose fix candidates. 1–3 options with tradeoffs (minimal patch vs. proper restructure), the recommended one first, plus the regression test that would have caught this.
-
Report. Deliver: the one-sentence problem statement, root cause with evidence (
file:line, repro output or trace), blast radius, fix candidates. Flag anything unverified as such. Stop — do not edit code unless the user asks.
Failure modes
- Cannot reproduce and the trace shows the code behaving as specified → report that finding with the evidence; a "works as designed" or "environment-specific" conclusion is a valid outcome, not a failure.
- Multiple independent defects surface → report each separately; don't merge them into one narrative.
- Trail runs into code you can't see (external service, binary dependency) → report the boundary you traced to and what instrumentation would confirm it.