ad-diagnose

<background_information> Implements WORKFLOW.md §15 per ADR-0021 (doc/adr/0021-diagnose-discipline.md). Disciplined diagnosis for hard bugs and performance regressions. Process scaffold; the output is the verified fix + regression test landing through normal commits.

The shape is grounded in Kernighan & Pike, The Practice of Programming (1999, ch. 5–6) and Karl Popper's falsifiability framing. The Phase-1 framing ("the loop is the skill — everything else is mechanical") is borrowed from mattpocock/skills with attribution.

Codex auto-trigger on description keywords is less mature than Claude Code's. If auto-invocation does not fire when the user mentions diagnosing, debugging, a performance regression, or building a repro, invoke this skill manually. </background_information>

Route elsewhere when:

• The bug is one-line obvious (typo, off-by-one) — fix it directly.
• The bug is a clean ground-truth-pair regression (test was passing, output unchanged, now failing) → ad-tdg (WORKFLOW §9).
• The technique itself is uncertain across multiple plausible approaches → ad-spike (WORKFLOW §14).
• The spec or expected behavior is unclear → ad-grill-me.

Phase 1 — build a feedback loop. This is the skill. Everything else is mechanical. A fast, deterministic, agent-runnable pass/fail signal for the bug is what enables every later phase. Without a loop, no amount of staring at code finds the cause.

Spend disproportionate effort here. Be aggressive. Refuse to give up.

Loop construction (try in roughly this order):

1. Failing test at the seam closest to the bug — unit, integration, or e2e.
2. Curl / HTTP script against a running dev server.
3. CLI invocation with a fixture input, diffing stdout against a known-good snapshot.
4. Headless browser script (Playwright / Puppeteer) — drives the UI, asserts on DOM/console/network.
5. Replay a captured trace — save a real network request / payload / event log, replay it through the code path in isolation.
6. Throwaway harness — minimal subset of the system (one service, mocked deps) exercising the bug code path in a single function call.
7. Property / fuzz loop — for "sometimes wrong output", run 1000 random inputs and look for the failure mode.
8. Bisection harness — if the bug appeared between two known states, automate "boot at state X, check, repeat" so git bisect run can drive it.
9. Differential loop — same input through old vs new (or two configs), diff outputs.
10. HITL bash script — last resort. If a human must click, drive them with a structured loop so the signal still flows back.

Iterate on the loop itself. Once you have a loop:

• Faster? Cache setup, skip unrelated init, narrow the test scope.
• Sharper signal? Assert on the specific symptom, not "didn't crash".
• More deterministic? Pin time, seed RNG, isolate filesystem, freeze network.

A 30-second flaky loop is barely better than no loop. A 2-second deterministic loop is a debugging superpower.

Non-deterministic bugs. Goal is not a clean repro but a higher reproduction rate. Loop the trigger 100×, parallelize, add stress, narrow timing windows, inject sleeps. A 50%-flake bug is debuggable; 1% is not — keep raising the rate.

When you genuinely cannot build a loop. Stop and say so explicitly. List what you tried. Ask the user for one of: (a) access to whatever environment reproduces it, (b) a captured artifact (HAR file, log dump, core dump, screen recording with timestamps), (c) permission to add temporary production instrumentation. Do not proceed to Phase 3 without a loop.