debugduck / rules

---
description: Systematic root-cause debugging. Use whenever something is broken, failing, flaky, slow, crashing, or behaving unexpectedly — bug reports, stack traces, failing or flaky tests, regressions, hangs, memory leaks, wrong output, CI-only failures, "works on my machine".
alwaysApply: false
---

# Debug — systematic root-cause debugging

Full procedure and stack-specific playbooks live in `skills/debug/`. **Read
`skills/debug/SKILL.md` first**, then load only the reference files relevant to this bug.

## Prime directives

1. **Reproduce before you diagnose. Diagnose before you fix.**
2. **The bug is where the evidence points**, not where it would be convenient. Intuition
   generates hypotheses; it never concludes.
3. **One variable at a time.** Simultaneous changes destroy causality.
4. **Binary search beats reading** — code path, git history, input, config, timeline.
5. **A root cause explains 100% of the observed evidence.** Unexplained details mean you're
   not done.
6. **Prove the fix by toggling it**: revert → bug returns; reapply → bug gone.
7. **Never suppress a symptom you don't understand** — no empty catch blocks, blind `?.`,
   retries, timeout bumps, or `# type: ignore` as a "fix".
8. **Label claims** `[observed]` / `[inferred]` / `[assumed]`.

## The six phases

1. **Reproduce** — deterministic, minimal, fast command. If it only fails in CI/prod, that
   environment difference is the primary lead. If you truly can't reproduce, say so and switch
   to evidence-mining; do not fix on spec.
2. **Observe** — read the *entire* error, stack traces bottom-up to the deepest frame you own.
   Logs, network, exit codes, DB state. No theorizing before looking.
3. **Localize** — **default: trace the whole path in one pass** (`skills/debug/references/trace-first.md`).
   Instrument every checkpoint from entry to symptom at once, numbered `CP01…CPnn`, **write down
   what each should print**, run once, and find the first checkpoint where actual ≠ expected;
   everything upstream is then ruled out. After instrumenting, **stop and hand over the run
   command — do not guess a fix while waiting for the output.** Fall back to bisection
   (midpoint probes, `git bisect run <repro>`, halving the input, working-vs-broken diff) when
   you can't re-run, the path is enormous, or logging perturbs the bug.
4. **Explain** — write the causal chain root → symptom. Ask "why" until you reach something
   worth fixing (the null check isn't the cause; *why it was null* is).
5. **Fix** — at the root, at the right layer, minimal. No opportunistic refactors in a bug fix.
6. **Prove** — original repro passes; toggle test; regression test verified to fail on the old
   code; broader suite green; grep for the same bug elsewhere; **remove all instrumentation**.

## Hypothesis ledger

Track it explicitly instead of flailing:

```
BUG: <expected vs actual>          REPRO: <command>   STATUS: reliable | n/10 | none
FACTS [observed]: <evidence with source>
H1: <hypothesis> → predicts <X>; TEST <cheapest discriminating experiment>; RESULT refuted/CONFIRMED
RULED OUT: <proven innocent>
ROOT CAUSE: <causal chain>
```

Prefer the hypothesis with the **cheapest, most discriminating** test. Design tests to refute.

## Stuck? Run the assumption audit

After **three refuted hypotheses**, stop generating a fourth — a premise is false:

- Am I running the code I think I am? (deliberate crash at the top — does it fire?)
- Stale build/cache/dist/`node_modules`/Docker layer/service worker/CDN?
- Right branch, commit, file, process, port, container, environment, config?
- Is the error even from my code, or from a dependency/proxy/platform?
- Is the **test** wrong? Did I misread the requirement?
- Did a dependency/API/schema change under me?

Past ~6 refuted hypotheses: report confirmed facts, ruled-out theories, top hypotheses, and
what you need. Don't thrash.

## Closing report

```
ROOT CAUSE / EVIDENCE / FIX (file:line) / VERIFIED (repro + toggle + regression test + suite) / NOT FIXED
```

## Playbooks in `skills/debug/references/`

**`trace-first.md`** (full-path instrumentation — read before adding any log statement, and
whenever the user asks for logs/tracing) · `techniques.md` (bisect, delta minimization,
differential) · `instrumentation.md` (logging, debuggers, stack dumps, profiling, cleanup) ·
`heisenbugs.md` (flaky/racy/CI-only) ·
`postmortem.md` (regression tests, siblings, blast radius) · `stacks/frontend.md` ·
`stacks/backend.md` · `stacks/library.md` · `stacks/browser-extension.md` ·
`stacks/github-app.md` · `stacks/cli.md` · `stacks/data.md` · `stacks/mobile-desktop.md`