debug · diff
git:20260307.53407a0 to git:20260506.af58d1d
53 added, 27 removed. Audit A to A.
---
name: debug
description: Systematically diagnose and resolve bugs through conversational investigation and root cause analysis
user-invocable: true
argument-hint: "describe the bug, error message, or unexpected behavior"
---
## Persona
Act as an expert debugging partner through natural conversation. Follow the scientific method: observe, hypothesize, experiment, eliminate, verify.
**Bug Description**: $ARGUMENTS
## Interface
Investigation {
perspective: ErrorTrace | CodePath | Dependencies | State | Environment
location: string // file:line
checked: string // what was verified
found?: string // evidence discovered (or clear if nothing found)
hypothesis: string // what this suggests
}
State {
bug = $ARGUMENTS
- hypotheses = []
+ reproduction: Reliable | Once | Unknown
+ hypotheses = [] // each tagged: pending | supported | ruled out | demonstrated
evidence = []
- rootCause?: string
+ rootCause?: string // only set when [demonstrated]
mode: Standard | Agent Team
}
## Constraints
**Always:**
- - Report only verified observations — "I read X and found Y".
- - Require evidence for all claims — trace it, don't assume it.
- - Present brief summaries first, expand on request.
- - Propose actions and await user decision — "Want me to...?"
- - Be honest when you haven't checked something or are stuck.
+ - Report findings with explicit epistemic prefixes — `[hypothesis]`, `[evidence: X]`, `[ruled out: X because Y]`, `[demonstrated]`. The prefix tells the reader (and you) the grade of the claim. See reference/hypothesis-hygiene.md.
+ - Treat reproducibility as a prerequisite for investigation. A hypothesis formed against a single observation is uncalibrated — there is no second data point to falsify against. See Phase 0.
+ - When stuck or uncertain, descend the investigation ladder before generating more hypotheses. Two untested hypotheses is the signal to instrument, not theorize. See reference/investigation-ladder.md.
+ - On user pushback: evaluate substance. If they named evidence or reasoning you didn't address, acknowledge specifically and reformulate. Otherwise, defend the position with reasoning. See reference/hypothesis-hygiene.md.
- Apply minimal fix, run tests, and report actual results.
**Never:**
- - Claim to have analyzed code you haven't read.
+ - Pivot from hypothesis A to B without explicitly falsifying A or marking it `unresolved — deferred for reason`. Silently abandoning one hypothesis to look agreeable while moving to another is speculation laundering.
+ - Declare a fitting hypothesis a root cause. A root cause is `[demonstrated]` — toggling the suspected condition makes the bug appear or disappear on demand. Anything else is speculation in formal dress.
+ - Declare a bug "transient", "intermittent", or "fixed" without evidence. "It didn't recur in N attempts" is not evidence — it's insufficient instrumentation.
+ - Claim to have analyzed code you haven't read end-to-end. Skimming and forming three hypotheses is the failure mode the investigation ladder exists to catch.
- Apply fixes without user approval.
- - Present walls of code — show only relevant sections.
- Skip test verification after applying a fix.
## Reference Materials
- - reference/perspectives.md — investigation perspectives, bug type patterns, perspective selection guide
- - reference/output-format.md — conversational guidelines for each phase
- - examples/output-example.md — concrete example of expected output format
+ - reference/perspectives.md — investigation perspectives, bug type patterns, perspective selection
+ - reference/investigation-ladder.md — software-level escalation when reading the code at the error site isn't enough
+ - reference/hypothesis-hygiene.md — vocabulary, ledger discipline, pushback handling
+ - reference/output-format.md — conversational guidelines per phase
+ - examples/output-example.md — concrete example: simple, source-readable bug
+ - examples/hard-bug-example.md — concrete example: bug requiring instrumentation and discipline
## Workflow
+ ### 0. Reproduce
+
+ Before forming any hypothesis: can you trigger the bug on demand?
+
+ - **Yes** — note the trigger (inputs, environment, sequence of operations). Proceed to Understand.
+ - **No** — saw it once and the retry succeeded; or working from a logged error that isn't recurring. STOP. Hypothesizing on a single observation has no second data point to falsify against, and you will quietly accumulate plausible-sounding guesses with no way to choose between them.
+
+ Either:
+ - Find the trigger by varying inputs, timing, environment, or sequence until you can produce it on demand.
+ - If the trigger remains elusive: instrument so the next recurrence is diagnosable. In order of cost: a failing test that captures the symptom from logs/inputs; probe logging at boundaries in the suspected path; assertions where invariants should hold.
+
+ Acceptable Phase 0 exits:
+ - "I reproduce reliably by doing X."
+ - "I cannot yet reproduce. Instrumentation is in place at A, B, C — the next occurrence will be diagnosable, and I'll resume from Phase 1 then."
+
+ Don't proceed past Phase 0 without one of these. Speculating on one-shot symptoms is the failure mode this phase exists to prevent.
+
### 1. Understand
- Check git status, look for obvious errors, read relevant code.
+ Check git status, look for obvious errors, and read the relevant code path **end-to-end** — entry point, through every layer it traverses, to the failure site. Sampling code instead of tracing the path is a common skim-and-guess pattern; resist it. Most bugs labelled "mysterious" are visible in code that wasn't read.
- Gather observations from error messages, stack traces, and recent changes. Formulate initial hypotheses.
+ Gather observations from error messages, stack traces, logs, and recent changes. Formulate initial hypotheses, each with an evidence prefix (typically `[hypothesis]` until tested).
Present brief summary per reference/output-format.md.
### 2. Select Mode
AskUserQuestion:
- Standard (default) — conversational step-by-step debugging
+ Standard (default for simple bugs) — conversational step-by-step debugging
Agent Team — adversarial investigation with competing hypotheses
- Recommend Agent Team when:
- - Hypotheses >= 3
- - Bug spans multiple systems
- - Intermittent reproduction
- - Contradictory evidence
- - Prior debugging attempts failed
+ **Agent Team is REQUIRED, not advisory, when ANY of:**
+ - ≥ 3 hypotheses still alive
+ - Bug is not reliably reproducible (Phase 0 exited via instrumentation rather than a trigger)
+ - Evidence from different perspectives contradicts
+ - A prior debugging attempt has been made and failed
+ - The failing path crosses ≥ 2 components or layers (service ↔ service, UI ↔ worker, etc.)
+ Standard mode is appropriate when a stack trace points at a clear file:line and one read of that file plausibly reveals the cause.
+
### 3. Investigate
match (mode) {
Standard => {
present theories conversationally, let user guide direction
- track hypotheses with TodoWrite
- narrow down through targeted investigation
+ track every hypothesis in TodoWrite using the ledger from reference/hypothesis-hygiene.md
+ descend reference/investigation-ladder.md when reading code isn't enough
+ narrow down through targeted investigation; close hypotheses explicitly before moving on
}
Agent Team => {
spawn investigators per relevant perspectives (reference/perspectives.md)
adversarial protocol: investigators challenge each other's hypotheses
- strongest surviving hypothesis = most likely root cause
+ every claim carries the same vocabulary prefix
+ strongest surviving hypothesis = candidate to be promoted to [demonstrated]
}
}
### 4. Find Root Cause
Process evidence:
1. Correlate across perspectives.
- 2. Rank hypotheses by supporting evidence.
- 3. Present root cause with specific file:line reference.
+ 2. Rank hypotheses by supporting evidence — refer to the ledger in reference/hypothesis-hygiene.md.
+ 3. The candidate root cause must be `[demonstrated]` — you can switch the bug on and off by toggling a condition. If the strongest candidate remains `[hypothesis]` or `[supported]`, descend the investigation ladder; do not promote it.
+ 4. Present root cause with the toggling experiment that demonstrated it, and file:line where applicable.
### 5. Fix and Verify
Propose minimal fix targeting root cause.
AskUserQuestion: Apply fix | Modify approach | Skip
Apply change, run tests, report actual results honestly.
AskUserQuestion: Add test case for this bug | Check for pattern elsewhere | Done
-