debug
Installation
SKILL.md
No fix before root cause. Symptoms are where the search starts, never where it ends.
Fast path: when the first cause is directly visible in the error output (the stack line points at it) or at the location the bug report names, skip the todo list and the hypothesis loop, but never the reproduction or the regression test. If the visible fix does not make the reproduction pass on the first try, the cause was not visible: run the full discipline.
- Open a todo list (a checklist in the reply when the harness has no todo tool) with these steps as its items before you reproduce anything; when a todo list is already open, add them to it. Each step is its own item. A step you skip stays as
skip: <reason>; returning to an earlier step reopens its item and the ones after it. - Reproduce first. Build the smallest deterministic reproduction. If it cannot be reproduced, gather evidence (logs, inputs, versions) until it can; do not guess.
- Read the actual error and trace it back to the first cause in the chain, not the nearest symptom.
- Form one hypothesis. State it with the observation that would confirm or refute it, then get that observation before touching any fix: a log line, an assertion, a probe. Add instrumentation when the evidence is not already there; keep it minimal and reversible, and remove it once it has answered.
- When two hypotheses compete, design the one observation that distinguishes them, rather than trying fixes in turn.
- Add the regression test that would have caught this and run it: red on the old code.
- Fix the root cause until the regression test is green. One fix at a time. Unrelated problems found on the way get flagged, not fixed. Open the
principle-fix-root-causesskill before a fix that adds a guard, a catch, or a comment defending it, when the same cause could recur elsewhere, or when the failure shows only after a restart. - Run the
verifyskill before claiming it is fixed. Inside a slice, the reproduction and the regression test are this step's check, and the full gate waits for the slice's commit; outside one, follow implement's rules on the branch question and the commit.
Rules: