atomic-debug

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).

2. Hypothesis table

List 3-5 candidates ranked by likelihood × cheapness to test.

| # | Hypothesis | Likelihood | Test cost | Test |
|---|-----------|-----------|-----------|------|
| 1 | req.body missing `user` after middleware reorder | high | 1m | log req.body at line 40 |
| 2 | DB returns null for new user before commit | med | 5m | run failing test in isolation |
| 3 | Type widening hides null in TS 5.5 upgrade | low | 10m | revert tsconfig strict change |

Order: highest (likelihood / cost) first. Don't list more than 5 — if you have more, you're guessing.

3. Run the cheapest test

Execute the test for hypothesis #1. Report the observation, exact and unedited.

If hypothesis confirmed → step 4. If refuted → cross it off, move to #2. Update the table. If observation surprises you → STOP, re-state the symptom. The mental model is wrong.

4. Root cause statement

Once a hypothesis is confirmed, write the root cause as a causal chain:

Root cause: middleware order change (commit abc1234) moved `parseBody` after `requireAuth`,
so `requireAuth` accesses `req.body.user` before it's populated → `undefined` →
`.id` throws TypeError.

ASCII flow diagram if the chain has ≥3 hops:

parseBody (moved after) → requireAuth runs → req.body = {} → req.body.user undefined → .id throws

If the root cause is a shared symbol, run atomic code callers <fn> (when an index is present) to check for other callers that assume the old behavior. A fix that ignores the blast radius leaves related callers broken — list any non-trivial callers in the root-cause statement.

5. Fix the cause, not the symptom

Propose the minimal fix at the root, not a guard at the symptom. State what regression test will lock the fix in.

Bad fix: if (req.body?.user) guard at line 42. Good fix: restore middleware order so parseBody runs before requireAuth. Add ordering test in middleware-pipeline.test.ts.

If the user wants the symptom guard anyway (e.g., defense-in-depth), add it ON TOP of the root fix, not instead of.