Triage the bug report in $ARGUMENTS: reproduce it, localize the root cause to file:line, assess impact, and scope the smallest correct fix. Diagnose only — do not implement the fix.
If $ARGUMENTS is empty, ask for the bug report (symptom, steps, expected vs. actual, environment) and stop. If it names a failing test, error string, or stack trace, start there.
Method
- Restate the bug in one line: observed behavior vs. expected behavior. If these are ambiguous from $ARGUMENTS, state your interpretation before proceeding.
- Detect the stack and conventions first: read the manifest (package.json, pyproject.toml, go.mod, Cargo.toml, Gemfile), test runner, and how the app is run. Do not assume a language or framework.
- Locate the surface: grep for the exact error message, failing symptom, or UI string from the report to find the entry point. Follow imports/calls inward from there.
- Reproduce deterministically. Prefer a failing automated test or a minimal command over manual clicking. Capture the exact command, inputs, and observed output. Reproduce on the current default branch (or the ref named in the report) before touching anything. If the failure is intermittent (race, timing, ordering, flaky test), run the same repro N times (default 20) and report the hit-rate as X/N — this rate is the frequency input for severity below.
- If you cannot reproduce, state precisely what blocks you — missing env var, credential, seed data, version, OS, external service, or a repro step the report omits — and give the one command or piece of info that would unblock. Stop there; do not guess a fix for an unreproduced bug.
- Find the root cause, not the symptom. Trace from the failure point (stack trace, first divergence from expected state) back to the earliest line that is actually wrong. Distinguish the trigger from the defect. If the file is under git with usable history, read the blame / recent commits touching that line to spot a regression window and its likely commit; if the project isn't git, or the line's history is squashed or vendored, skip this and rest the diagnosis on the code and mechanism alone.
- Prove causation before claiming it: identify the specific input, state, race, or edge case (null/empty, boundary, concurrency, encoding, timezone, off-by-one, unhandled error path) that makes the code misbehave. If you cannot name the mechanism, say the cause is still a hypothesis.
Blast radius
- Who/what is affected: which users, requests, or data, and under what conditions (always vs. specific input/config).
- Data at risk: any corruption, loss, leak, or incorrect persisted state. Note if the bug is silent (wrong data, no error).
- Severity: critical / high / medium / low, justified by frequency x impact and whether a workaround exists. Base frequency on evidence — always-fails, tied to a specific input/config, or the measured hit-rate from step 4 for intermittent bugs — not a guess.
- Other call sites sharing the faulty code path — grep for them; the same defect often has siblings.
Output
- Summary — one line: what's broken, for whom.
- Reproduction — exact steps/command and observed vs. expected output, or the specific missing info blocking repro.
- Root cause — the defect with
path/to/file.ext:line, and the mechanism that triggers it. - Blast radius & severity — from the section above.
- Smallest fix scope — the minimal change that corrects the root cause, named as file:line/function and approach. Call out anything that looks tempting but is out of scope.
- Regression test — the specific test to add: its input, assertion, and where it belongs, such that it fails today and passes once fixed.
Rules
- Never edit source to implement the fix; a temporary probe (log line, failing test) is allowed but revert it before finishing.
- When you have more than one unproven cause, present them as hypotheses ordered most- to least-likely, each with the file:line and check that would confirm or kill it.
- Prefer the narrowest fix that fully resolves the root cause. Do not propose refactors, style changes, or fixes to unrelated issues you notice — list those separately as one-line notes.