Bug Triage · diff
git:20260908.b205970 to git:20261031.5d810c9
78 added, 9 removed. Audit A to A.
---
name: "Bug Triage"
- description: "Turn a bug report, logs, and reproduction steps into a testable diagnosis and a focused fix plan."
+ description: "Turn a bug report, logs or a failing test into a reproduction, ranked causes, one diagnostic step that separates them, the smallest fix, and a verified result. Use when something fails and the cause is not yet known."
---
# Bug Triage
+ ## When to use
+
+ - A user, a test, a log or a QA run shows a failure and the cause is not known.
+ - Not for a review of a change that has no reported failure. Use Change Review for that.
+ - Not for a pass or fail check of a live site. Use Acceptance Check for that.
+
## Inputs
- Start from expected versus actual behavior, the failing version, and available logs. Request a missing reproduction detail only when it blocks the next useful check.
+ 1. **The failure.** Expected result, actual result, and the exact error text. Get it from the issue
+ (`gh issue view <number>` or an installed plugin such as Linear or Sentry), from a failing test, or from
+ the user. If the user only describes it, ask them to paste the error and the steps.
+ 2. **The version.** Commit, branch, release or build where it fails. Note where it last worked, if known.
+ 3. **The code.** The workspace repository. Without it, ask for the relevant files or a stack trace.
- ## Workflow
+ If one detail blocks the reproduction, ask for that one detail with `ask_user`. Do not ask for more.
+ Never copy keys, tokens or passwords from logs into your notes or replies.
- 1. Build the shortest reproduction and locate the first observable divergence. Preserve exact error text and relevant input values without copying credentials.
- 2. List at most three plausible causes, ranked by evidence. Choose a check that distinguishes them instead of changing several things at once.
- 3. Separate the trigger from the root cause and any secondary errors. If evidence contradicts a hypothesis, discard it explicitly.
- 4. Propose the smallest fix and a regression check. State whether reproduction and verification actually ran.
+ ## Steps
- ## Deliverable
+ 1. **Reproduce.** Write the shortest steps or the smallest test that shows the failure. Run it. Record the
+ command and the output. If you cannot reproduce it, say so and keep the report's evidence as the source.
+ 2. **Locate.** Find the first point where the actual state differs from the expected state. Read the code
+ there and its callers. Keep the trigger, the root cause and later secondary errors apart.
+ 3. **Hypotheses.** Write at most three causes. Rank them by the evidence. Give each one a prediction: "if
+ this is the cause, then <observation>".
+ 4. **Separate.** Choose ONE diagnostic step whose result differs between the top hypotheses: a log line, a
+ breakpoint, a changed input, `git bisect`, or one value printed. Run it. Discard each hypothesis that the
+ result contradicts, and say so.
+ 5. **Fix.** Make the smallest change that removes the root cause, only when the user asked for a fix. Do not
+ change unrelated code or several things at once.
+ 6. **Verify.** Run the reproduction again: it must now pass. Run one regression check near the change: the
+ existing test file for that code, or a new focused test that failed before the fix.
+ 7. **Report.** Say which steps ran and which did not.
- Return reproduction steps, evidence, likely cause with confidence, proposed correction, and verification steps. If unresolved, give the single most useful next observation.
+ ## Rubric
+
+ Confidence in the cause:
+
+ - **Confirmed:** the reproduction failed before the fix and passes after it, and the diagnostic step
+ pointed at this cause.
+ - **Likely:** the diagnostic step supports this cause, but the fix is not yet verified.
+ - **Possible:** it fits the evidence, but no step separated it from the other causes.
+ - **Unknown:** no reproduction. Give the next observation that would help most.
+
+ Never call a cause Confirmed without a run before and after the fix.
+
+ ## Output
+
+ ```
+ Bug: <one line> — <version>
+ Status: <Confirmed | Likely | Possible | Unknown>
+
+ Reproduction: <command or steps> → <error, exact text>
+ First divergence: <file>:<line> — expected <x>, got <y>
+
+ Hypotheses
+ 1. <cause> — <evidence> — <kept | discarded: reason>
+ 2. ...
+
+ Diagnostic step: <what ran> → <result>
+ Root cause: <one or two sentences>
+ Fix: <file>:<line> — <change>, or "proposed, not applied"
+
+ Verification
+ - Original failure: <command> → <pass/fail>
+ - Regression check: <command> → <pass/fail>
+ Not run: <check> — <reason>
+ ```
+
+ ## Approvals and stop conditions
+
+ - Diagnose first. Edit code only when the user asked for a fix.
+ - Do not commit, push, merge, deploy or close the issue without the user's yes.
+ - Do not run commands that delete data, change production, or send messages to reproduce a bug. Ask first.
+ - Stop after two diagnostic steps that do not separate the hypotheses. Report what you learned and ask.
+
+ ## Common failures
+
+ - Changing three things at once, so nobody knows which one fixed it.
+ - Fixing the secondary error that the log shows last, not the first divergence.
+ - "Fixed" without a run of the original reproduction.
+ - A fix with no regression check, so the bug returns in the next change.
+ - Keeping a hypothesis after the evidence went against it.