Debug

Debug

Prove the mechanism before fixing it. The enemy is the nearby plausible patch that hides today's symptom without explaining it. The overcorrection is investigating after the evidence already identifies one causal line and predicts the failure. Stop investigating at proof, then implement the smallest predicted change.

No production edit before a reproduction. If the symptom cannot be triggered, the current deliverable is reproduction evidence, not a fix.

Activation gate

Treat the cause as proven only when observed evidence identifies one causal line or boundary and one mechanism that predicts the symptom. A diagnostic naming a file and line is sufficient only when the named source contains the invalid symbol, type, or operation described. Proven cause means skip investigation and fix directly; otherwise run the loop.

The loop

1. Reproduce. Capture a failing test, repeatable command, or specific input. Run it as one bare command and, when its output would exceed the cap, redirect it to .git/debug-repro.log and read tail -n 40 of that log; the same rule holds for every later run in this loop, because a pasted log is carried into every turn after it. When unavailable infrastructure blocks the original symptom, name the missing dependency and reproduce at the first repository-owned boundary that supplies input to it, without claiming equivalence. After reproduction, apply the test-design row in References before the first affected test or production edit.
2. Instrument. Keep two hypotheses not contradicted by the reproduction. Add one observation that produces different outputs for them at their first divergent boundary. Delegate locating that boundary's file and its callers to the exo:explorer agent and read here only the ranges it names; a search run here stays in context for every later step.
3. Isolate. Remove inputs or branches until removing one more makes the symptom disappear. Use an ephemeral copy when isolation would disturb a shared file. Two instrument-and-isolate rounds that leave both hypotheses standing end the loop: report the reproduction, both hypotheses, and every observation, and stop, because a third round without a discriminating observation is guessing.
4. Predict, then fix. Before editing production code, state the causal line, the output that will change, and why, then settle where the fix commits as ../implementing/references/workspace.md says. Apply the security and data-migration rows in References to that predicted change, then make only the change required by the prediction.
5. Prove. Re-run the original reproduction and isolated case. Run the repository's required suite under the Step 1 output rule, then grep the log for failures instead of printing it. Close under the closing rule in using-exo: the mechanism first, then the output lines that prove it, at most ten, with the log path for the rest.
6. Retain project knowledge. Select root AGENTS.md when it exists, otherwise root CLAUDE.md. If reproduction or proof reveals a build, test, or run command, or a failure-causing repository gotcha, absent from that selected file, append one line there. If neither file exists, create nothing. Do not record session history.
7. Fresh eyes. Skip this step when the caller states that a pull-request review follows: that review is the one fresh look. Otherwise, when one or more size facts are true—more than two changed files, a dependency, a public signature, a crossed persisted format or security boundary, or a required file outside initial inspection—run the code-review skill on the session's model on its default target at low effort up to five changed files or 200 changed lines and medium above, and fix each confirmed correctness finding under Step 5's proof; when that skill is absent, follow implementing-batch's Fresh eyes step: read ../implementing-batch/references/critique.md now and not earlier, run its checks, and report that no separate context was available.

Performance branch

A speed-only symptom requires measurement before a hypothesis or edit. Read ../implementing-batch/references/performance.md after identifying a speed-only complaint and before measuring. Do not load it for correctness failures.

References

Judgment

• Outside a read-only planning turn, debug outranks shaping, planning, and implementing-batch until the cause is proven; at proof debug applies the predicted fix itself through Steps 4 to 7 and offers implementing-batch on the next-stage question for edits beyond the predicted change. Inside one, planning owns the turn and schedules reproduction as its first phase.
• A user-stated cause outranks investigation only after it matches the source and predicts the reproduction.
• Reproduction and instrumentation outrank intuition, including the first hypothesis.
• Go back to Step 1 instead of adding another patch when any of these shows: the repair reaches into a second owner; an old route and its replacement both still run; supporting code keeps growing while the behavior stays the same; or the path from input to symptom cannot be followed in a single reading. Each one means the proven cause was not the real cause.
• After Step 7 the predicted fix commits in Conventional Commits where Step 4 placed it. Edits the proof leaves beyond it end the turn on the next-stage question in using-exo, offering implementing-batch for them; with none left, the turn ends on ../implementing/references/finishing.md. After a compaction notice, re-run the Step 1 reproduction before the next edit, because the command, not memory, says whether the symptom still exists.