git:20261006.526f323 to git:20261015.c0bb9cf

7 added, 18 removed. Audit A to A.

---

name: debugging

description: "Use for runtime bugs: crashes, wrong output, intermittent or silent failures, flaky tests, code that works locally but not in prod. Not for build failures or type errors; those go to build-fixer."

---

# Debugging

- A bug is not fixed until you can explain why it happened, not just that it stopped happening.

- ## The loop

- 1. **Reproduce.** Get a repro that fails on demand, ideally scripted. If you can't make it fail on command, you don't understand it well enough to fix it.

- 2. **Form at least three ranked hypotheses**, each with a discriminating test: a specific observation that would confirm one hypothesis and rule out the others. A hypothesis you can't falsify isn't one. Rank by prior probability times how cheap the test is to run; do the cheap, likely ones first.

- 3. **Instrument before modifying.** Add logging, breakpoints, or assertions to observe the running system before you change any behavior. Record the observed values verbatim, not a paraphrase of what you think you saw.

- 4. **Test the top hypothesis.** Run the discriminating test. If it fails to confirm, move to the next hypothesis; don't patch around an unconfirmed cause.

- 5. **Fix**, once a hypothesis is confirmed by observation, not by a plausible story about the code.

- 6. **Verify the repro is gone AND adjacent behavior is unchanged.** Re-run the original repro plus the nearest related paths. A fix that silences the symptom without touching the mechanism will resurface elsewhere.

- ## Escalation

+ Reproduce the runtime failure before changing behavior. Capture the exact command, inputs, environment, and observed failure. If reproduction is unavailable, state that limit and gather evidence rather than declaring a fix.

- After two failed fix attempts on the same bug, stop iterating alone. Call the `advisor` tool first when you have it; when it is off or its guidance does not unblock you, consult the architect, handing over the attempt timeline: what each hypothesis was, what the discriminating test showed, and why it was ruled out. Two failed rounds is a signal that the mental model of the system is wrong, not that the third attempt will get lucky.

+ Form falsifiable hypotheses and test the cheapest useful distinction. Observe actual values with targeted instrumentation before patching. Change only the confirmed cause; explain the causal chain rather than treating a disappearing symptom as proof.

- ## Artifact hygiene

+ Rerun the same reproducer and nearby affected behavior. Add a regression test where practical. Remove only temporary instrumentation you added, review the diff, and log each build, test, or lint run with `evidence_log` and its real exit code.

- Every repro script, log statement, and temporary breakpoint you add during a debugging session gets tracked and removed before the task is done. Keep a running list of what you added and where; when the fix is verified, walk the list and revert or delete each item. A session that leaves stray instrumentation, debug prints, or scratch scripts behind is not finished, regardless of whether the bug is fixed: check `git diff` shows only the fix and its test before calling it done. Record verification with the `evidence_log` MCP tool.

+ After two failed fix attempts, stop repeating edits and return the evidence and attempt history to the primary agent; recommend `oh-my-claudeagent:architect` for deeper diagnosis. Build, type, dependency, and toolchain failures belong to `oh-my-claudeagent:build-fixer`.

- ## Boundary with build-fixer

+ For deeper diagnostic techniques, read `references/methodology.md` or `references/diagnostics.md` as needed.

- Build failures, compile/type errors, and toolchain or dependency breakage go through the build-fixer flow: that agent owns anything that keeps the build from succeeding. This skill owns misbehavior that shows up only once the code is running: wrong output, crashes, hangs, races, and anything that passes a build but fails a real scenario.

+ ## Claude Code

- Depth reference: `references/methodology.md` (hypothesis quality, instrumentation discipline) and `references/diagnostics.md` (runtime observation patterns, bisecting, concurrency failures, environment differences).

+ When `advisor` is available, consult it before escalating to the architect. If it does not unblock the diagnosis, include its guidance and the observed results in the escalation.