debuglisted

> `<cai>` is the cai-codex command line that `$setup` wrote into your instructions (the cai-codex block in AGENTS.md). `<cai-root>` is what `<cai> --root` prints. # Debugging A bug fixed without finding its root cause comes back, usually somewhere worse. The rule below exists because the tempting move — change the line the stack trace points at, run it once, ship it — produces a fix that looks right and isn't. ## The rule **No fix before the root cause is found and stated.** "It's probably X, let me try changing that" is a guess wearing a fix's clothes. If you cannot say in one sentence why the bug happens, you are not ready to touch the code. This applies double under time pressure. Guessing under a deadline is how a fifteen-minute bug turns into a three-hour one. Redact secrets from anything shown below (a reply, a diagnosis document, a temporary log) — write `<REDACTED>` in their place, and build commands against environment variables so a credential never has to appear at all. ## Step 1 — Reproduce it, on purpose Find the exact steps that trigger it, every time. Not reproducible yet → gather more data (logs, a smaller repro case, the exact input); ten ways to build one when it isn't obvious are in `<cai-root>/skills/debug/references/feedback-loops.md`. A fix aimed at a bug you can't reliably trigger is aimed at nothing. **Done when you can point at one command**: named, rerunnable, already run this session, its redacted output pasted, its failure matching the sy