atomic-debug

Debug by hypothesis, not by guessing. Cheapest test first. Root cause, not symptom.

Auto-trigger on:

• Error message or stack trace pasted
• "broken", "doesn't work", "failing", "crash", "regression", "flaky"
• Test failure output

Explicit: /atomic-debug or "let's debug X".

Five steps

1. State the symptom exactly

One sentence. Quote the exact error. Note what changed recently (commit, dep, env) if known.

Symptom: `POST /users` returns 500 since commit abc1234. Stack: `TypeError: Cannot read 'id' of undefined at users.ts:42`.

1b. Locate the surface (when not already in context)

Code-intel first (when an index is present). Before dispatching an agent, try atomic code explore "<symptom as a natural-language query>" for a one-shot digest of the failure neighborhood, or atomic code callers <suspect-fn> when the symptom names a symbol. This is a single shell command — cheaper than spawning an investigator and it returns caller-graph context grep would have to reconstruct. Fall through to the investigator dispatch below only when the index is absent or the query returns nothing useful.

If the suspect code isn't already mapped in the conversation (no file:line references, no recent reads of the relevant module), dispatch atomic-investigator BEFORE forming the hypothesis table. Haiku-backed and read-only, so it's cheap. Give it a focused brief:

Locate <symptom-relevant surface>. Report file:line table.

Example: "Locate the request pipeline for POST /users — middleware order, body parsing, auth check. Report file:line table."

Use its file:line — what table as the evidence base for the hypothesis table. The investigator spends Haiku tokens so the main context (running this skill) doesn't burn Sonnet/Opus on grep work.

Skip this step when: the symptom names the exact file:line (e.g. the stack trace pinpoints it), the bug is in code already in context, or the symptom is too abstract to map (e.g. "the build is slow" — there's no surface yet, hypotheses come first).