debug — find the cause before you touch the fix

debug is the on-demand diagnosis discipline of the rsc-sdd chain. Something is broken — a test went red, a crash landed, a result is wrong, a regression appeared — and the strongest pull in the room is to change code until the symptom disappears. That pull is the enemy. A symptom that vanishes under a guessed edit usually moved; it rarely died. This skill replaces guess-and-patch with a short, evidence-driven loop that ends only when one confirmed cause has been named, fixed, and proven gone.

The one rule everything else serves: no fix before a reproduced, isolated, confirmed cause. If you cannot make the bug happen on demand, you cannot know you fixed it — you can only know the symptom stopped showing, which is not the same thing.

This is a process skill: it owns the method, never the instruments. The test runner, debugger, race detector and profiler belong to whichever stack the failure lives in — pull them from the delegation table below.

Model tier — heavy (opt-in routing)

This phase's default model tier is heavy — root-cause diagnosis is deep reasoning. Routing is off unless models.enabled: true in 02-DOCS/wiki/sdd/config.yaml. When on: resolve this phase's tier (models.overrides wins over models.phases), map it to a model via models.tiers, and apply per ../sdd/references/model-routing.md — announce the switch per the accompaniment dial when it differs from the session model, and dispatch any Task/parallel subagents on that model. Routing off or no profile → honor the session model silently. Never fake a switch a tool can't make; skip routing on a one-line change.

Read the room first (accompaniment dial)

Before diagnosing, read 02-DOCS/wiki/harness/user-profile.md for the technical + accompaniment level and match it; with no profile yet, assume non-technical — narrate the reasoning plainly and never apply a behavior-changing fix without a quick confirm. The method never changes with the dial — the volume does.

Level	While diagnosing you show…	Questions you ask
L0 terse	the confirmed cause and the one-line fix, once found	none unless you need a missing repro detail
L1 brief	the cause + one line of why it produced this symptom	only what you can't observe yourself (e.g. exact error text)
L2 decisions	each step's finding (repro, the half that isolated it, the cause)	confirm before a fix that changes behavior beyond the bug
L3 full	narrate the whole loop, teach the binary-search reasoning aloud	ask to contextualize the environment, recent changes, expectations

The loop — five steps, never skipped, never reordered

REPRODUCE   → make the bug happen on demand. A reliable repro (or a quantified flake rate) is the
              entry ticket. No repro → you are not debugging yet, you are guessing. Capture the
              exact command, input, env, and the verbatim error/stack.
ISOLATE     → binary-search the cause. Halve the surface each step — git bisect across commits,
              comment/branch to split code paths, remove inputs until the minimal failing case
              remains. Change ONE variable at a time; note what each change does to the symptom.
HYPOTHESIZE → from the isolated evidence, state ONE falsifiable cause: "X happens because Y, and if
              so, changing Z will flip the result." A hypothesis you can't disprove isn't one.
FIX         → make the smallest change that addresses the *cause* (not the symptom). First, encode
              the bug as a failing test (it should now go red for the real reason) — then fix until
              it's green. Treat the test as the proof the cause was real.
VERIFY      → re-run the repro: symptom gone. Re-run the new test: green. Re-run the surrounding
              suite: still green (no new red). For a flake, run it enough times to show the rate
              dropped to zero. Only now is it fixed.

Reproduce — the entry ticket

A bug you cannot reproduce is not a bug you can fix; it's a rumor. Pin it down:

• The exact invocation (command, request, UI steps), the input that triggers it, the environment (OS, versions, env vars, branch/commit), and the verbatim error + stack trace — not a paraphrase.
• For a flake, reproduction means a rate: run it N times, record k/N failures. "Intermittent" is a measurement to take, not a property to accept. A flake almost always means shared state, order dependence, a real race, time/timezone, or network — name which.
• If you genuinely cannot reproduce, that is the finding. Say so, gather more signal (logs, a failing CI run, the user's exact steps), and do not apply a speculative fix to a bug you can't trigger.

Isolate — binary-search the surface

The cause is somewhere in a large space; cut it in half, repeatedly, with evidence.

• Across history: git bisect between a known-good and known-bad commit to land on the exact change that introduced it. Let the repro be the bisect's good/bad oracle.
• Across code: disable/short-circuit half the suspect path; see which half keeps the symptom.
• Across inputs/data: shrink the failing input to the minimal case that still fails.
• One variable per step. Two changes at once and you've learned nothing about either. Write down what each step did to the symptom — the trail is the diagnosis.

Delegate the stack-specific tooling (debugger, race detector, profiler, query plan) to the stack skill below; debug decides what to halve, the stack skill provides the instrument.

Hypothesize → Fix the cause, not the symptom

State the cause as a sentence you could be wrong about, then act on it:

• Fix the cause, not the symptom. A try/except that swallows the error, a retry that hides a race, a sleep that papers over an ordering bug, a bumped timeout — these relocate the symptom and leave the cause armed. If your fix doesn't reference the cause you named, it's a patch on a guess.
• Encode the bug as a test first. The failing test that reproduces the bug is your regression guard; watch it go red for the real reason, then make it green. A fix with no test means the next change can resurrect the bug silently.
• Keep the change minimal. Resist "while I'm here" refactors — they confound the verification and bury the one line that mattered.

Verify — the symptom and the test, both

The fix is unproven until the original repro no longer fires and the new test is green and the surrounding suite stayed green. For a flake, re-run enough times to show the failure rate is zero, not merely lower. Then hand the whole-gate re-run (lint/type/full suite/audit) to verify — that gate, not this skill, is what licenses the word "done".

Delegating the stack tooling (don't reinvent the instruments)

debug owns the loop; the stack skill owns the debugger, the flake mechanics, and the profiler.

Stack / layer	Where the instruments live	What you pull
FastAPI / async Python	../fastapi/references/testing.md	pytest -x --lf, pdb/breakpoint(), async task/race traps, transactional-rollback fixtures to kill state bleed
Go services	../go/references/testing.md	go test -race, -run/-count=1 to force a flake, delve, pprof, errors.Is/As unwrapping
Next.js / React	../nextjs/references/testing.md	Vitest --no-isolate/.only, Playwright trace viewer, RSC vs client boundary errors, hydration mismatches
Flutter / Dart	../flutter/references/testing.md	flutter test --plain-name, widget pump/settle timing, DevTools, golden diffs
Postgres / data layer	../postgresdb/SKILL.md	EXPLAIN ANALYZE, isolation-level/locking races, constraint violations, migration-order bugs
Security-shaped failure	../secure-coding/SKILL.md	auth/authz edge cases, injection, secret/leak paths surfacing as "weird" failures

If the failure spans two stacks (a Next.js call into a FastAPI endpoint), reproduce at the boundary first — isolate which side actually fails before you open either stack's debugger.

Log the diagnosis (the 02-DOCS trail)

When the cause is non-obvious — a race, an order dependency, an environment-only failure, a regression a reviewer would otherwise have to rediscover — append a short entry to 02-DOCS/wiki/sdd/decisions.md (append-only; create it if absent and add a row to the root CLAUDE.md ## Knowledge map under the sdd/ topic). One entry:

## YYYY-MM-DD — bug: <symptom in five words>  (feature: <slug>)
Repro      — the exact command/input that triggered it
Cause      — the ONE confirmed root cause (not the symptom)
Fix        — the minimal change + the regression test that guards it
Why missed — what let it through, so the class of bug doesn't recur

Skip the trivial ones (a typo'd variable). Log the cause a future debugger would pay to know.

Anti-patterns

Anti-pattern	Why it fails
"I see the likely line — let me just change it and see."	That's guess-and-patch. Reproduce first; a fix to an untriggered bug proves nothing.
"It's intermittent, you can't really reproduce it."	"Intermittent" is a rate to measure (k/N), not an excuse. Flakes have causes: state, order, races, time.
"Wrapping it in try/except makes the error go away."	You hid the symptom and left the cause armed. Fix the cause, not the crash site.
"Adding a sleep/retry/bigger timeout fixes the flake."	It relocates the race. Name the shared state or ordering bug; fix that.
"I'll fix it now and add a test later if there's time."	The bug-reproducing test IS the fix's proof. No red-for-the-right-reason test = unproven fix.
"I changed three things and now it works."	You can't say which mattered or why. One variable per isolate step; revert the rest.
"The repro's gone, ship it."	Gone how? Re-run the repro AND the new test AND the suite. Symptom-absent ≠ cause-dead.
"It works on my machine, so it's fixed."	Environment IS a variable. Reproduce where it actually fails (CI, prod-like) before claiming done.
"This bug is obvious, skip the loop."	Obvious causes are the ones that turn out to be a second bug masking the first. Run the loop.

Red flags — stop and re-route

• The "bug" is a spec contradiction or unclear requirement, not a defect → route to clarify / analyze; debugging won't fix an ambiguity.
• The fix grows past the cause (you're refactoring "while you're here") → split it out; keep the fix minimal and verifiable. Improvements go through implement.
• You're tempted to disable, skip, or delete the failing test to make the suite green → that's the bug winning. Never ship around a red test; diagnose it.
• You "fixed" it but can't point to the cause you named → you patched a symptom. Resume at HYPOTHESIZE.
• The cause violates the constitution (e.g. it only "works" by breaking a quality bar) → surface it; don't smuggle a violation in under the banner of a bugfix.

Checklist (copy per bug)

- [ ] REPRODUCE: exact command/input/env + verbatim error captured; repro reliable (or flake rate k/N measured)
- [ ] ISOLATE: surface halved with evidence (bisect / code split / minimal input); ONE variable per step
- [ ] HYPOTHESIZE: one falsifiable cause stated ("X because Y; changing Z flips it")
- [ ] FIX: bug encoded as a failing test (red for the RIGHT reason); smallest change to the CAUSE
- [ ] VERIFY: repro no longer fires; new test green; surrounding suite still green; flake rate → 0
- [ ] Non-obvious cause logged to 02-DOCS/wiki/sdd/decisions.md
- [ ] Handed the whole-gate re-run back to verify; resumed implement where the failure interrupted it

Where you are in the chain

debug is on-demand, callable from any phase — most often pulled in mid-implement when a test fails for a reason you don't understand, or by verify when its gate reports a failure it won't diagnose. It is not a fixed step in the line constitution → specify → clarify → plan → tasks → analyze → implement → verify → review → ship.

Next: when the one confirmed cause is fixed and proven gone, hand back. Return to implement to resume the interrupted task, or to verify to re-run the full gate and let evidence — not the relief of a quiet terminal — declare the work done.