Debug

---
name: debug
description: Hypothesis-driven defect isolation — stack-trace forensics, breakpoint strategy, state inspection, and root-cause confirmation via minimal repro. Use when a defect surfaces (test failure, crash, exception, wrong output, intermittent flake) and the cause is not immediately obvious from the change set.
---

A bug is a falsified assumption. Find the assumption, falsify it deliberately, observe the divergence, narrow until one line owns the lie. No speculation, no shotgun edits, no "fix and rerun" guessing.

## When to Apply / NOT

Apply: test fails and cause unclear; production stack trace; intermittent / flaky behavior; wrong output without crash; regression after known commit window; heisenbug.

NOT apply: performance regression with correct outputs; security defect; symptom obvious from one-line read; architectural confusion.

## Anti-patterns

- **Shotgun debugging**: editing several files hoping one fixes it.
- **Print-and-rerun**: adding logs without a target observation.
- **Premature fix**: patching symptom before isolating root cause.
- **Ignoring the trace**: stack frames are evidence.
- **Changing two variables at once**: defeats falsification.
- **Deleting the failing test**: capturing the bug is the asset.

## Hypothesis Loop (language-neutral)

1. **Observe** — Reproduce the failure deterministically.
2. **Trace** — Read the failure artifact (stack, log, core dump).
3. **Hypothesize** — One falsifiable claim. Rank hypotheses by likelihood.
4. **Instrument** — Insert minimum probe (breakpoint, structured log, assertion).
5. **Run** — Execute the minimal repro.
6. **Confirm or refute** — If refuted, demote and pick next hypothesis.
7. **Narrow** — Binary-search the suspect range. Use `git bisect` for regressions.
8. **Confirm root cause** — Inverse test: removing/altering the cause must restore correctness.
9. **Hand off** — Forward to TDD: minimal repro becomes permanent failing test.

## Stack-Trace Reading

- **Top frame is innermost**: the failure point.
- **Cause vs context**: An exception's `caused by` chain encodes *why*; the stack encodes *where*.
- **Async traces**: virtual stacks drop frames between awaits — capture causal context.
- **Symbol fidelity**: Strip-mode binaries lose frame names. Build with debug info.
- **Inlined / optimized frames**: `<inlined>` markers signal source-line-to-instruction map is approximate.

## Parallel Tooling

| Family | Live debugger | Postmortem / record | Remote attach |
|---|---|---|---|
| Systems (C/C++/Rust) | `gdb`, `lldb`, `rust-gdb`, `rust-lldb` | `coredumpctl` + `gdb core`, `rr record/replay` | `gdb -p <pid>` / `lldb -p <pid>` |
| Python | `pdb`, `ipdb`, `pdbpp`, `breakpoint()` | `faulthandler`, `py-spy dump`, traceback module | `debugpy --listen` |
| Go | `dlv debug`, `dlv test`, `dlv attach <pid>` | `runtime/pprof`, GOTRACEBACK=crash | `dlv connect <addr>` |
| Java/Kotlin | IntelliJ debugger, `jdb` | hs_err logs, JFR, heap dump (`jmap`) | JDWP `-agentlib:jdwp=...` |
| JavaScript/TypeScript | `node --inspect`, Chrome DevTools | `--report-uncaught-exception` reports | `--inspect=0.0.0.0:9229` |
| OCaml | `ocamldebug`, `Printexc.record_backtrace true` | core file + `ocaml-gdb`, memtrace | `ocamldebug -s <socket>` |

Use `procs` (not `ps`) for PID. Use `bat -P -p -n` (not `cat`) for trace files. Use `git grep -n -C 3 'pattern'` (not `grep`) for callsites.

## Constitutional Rules

1. **Reproduce before fixing**.
2. **One hypothesis at a time**.
3. **Evidence over inference**.
4. **Capture the bug as a test** (hand to TDD).
5. **Confirm with inverse**.
6. **Bisect for regressions**.
7. **No silent edits**.