atman-33 Investigate Bug Report
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.