Diagnosing Bugs

A six-phase discipline for diagnosing hard bugs, sourced from mattpocock/skills (MIT). Phase 1, the core of the skill, builds a tight, red-capable feedback loop before any hypothesizing: a failing test, curl/HTTP script, CLI invocation diffed against a snapshot, headless-browser script, replayed captured trace, throwaway harness, property/fuzz loop, bisection harness, differential loop, or as a last resort a human-in-the-loop bash script following a bundled template - tried roughly in that order, then tightened for speed, sharper assertions, and determinism by pinning time, seeding RNG, and isolating filesystem and network. For non-deterministic bugs the goal is raising the reproduction rate rather than chasing a clean repro; if no loop can be built at all, the skill requires stopping explicitly and asking the user for environment access, a captured artifact, or permission to add temporary production instrumentation, rather than proceeding to hypothesize blind. Phase 1 completes only when there is one already-run, pasted command that is red-capable, deterministic, fast, and agent-runnable. Phase 2 reproduces and then minimizes the repro to the smallest scenario that still fails, cutting inputs, callers, and config one at a time until every remaining element is load-bearing. Phase 3 requires generating 3-5 ranked, falsifiable hypotheses before testing any of them, each stated as "if X is the cause, then changing Y will make the bug disappear," and showing the ranked list to the user first since they often have domain knowledge that instantly re-ranks it. Phase 4 instruments one variable at a time, preferring a debugger or REPL breakpoint over logs, tagging every debug log with a unique prefix for one-command cleanup, and for performance regressions establishing a baseline measurement before bisecting rather than trusting logs. Phase 5 writes the regression test before the fix, but only at a "correct seam" that exercises the real bug pattern as it occurs at the call site - if no correct seam exists, that absence is itself the finding to flag. Phase 6 requires a checklist before declaring done: the original repro no longer reproduces, the regression test passes or the missing seam is documented, all tagged debug instrumentation is removed, throwaway prototypes are deleted, and the correct hypothesis is recorded in the commit or PR message; only after the fix lands does it recommend escalating to a separate architecture-improvement skill if the root cause was architectural.

Use for hard bugs that resist a quick fix - the skill instructs reading CONTEXT.md and relevant ADRs first to build a mental model before diagnosing. Phases should be skipped only when explicitly justified, and the skill explicitly forbids jumping to a hypothesis before a red-capable command exists, since jumping straight to a hypothesis is the exact failure the skill is designed to prevent.

Input is a described bug symptom and access to the codebase or a running environment. Output is a red-capable reproduction command, a ranked hypothesis list, a minimized repro, a fix with a regression test at a correct seam or a documented absence of one, and a post-mortem noting the confirmed cause and any recommended architectural follow-up.

References a bundled scripts/hitl-loop.template.sh for structuring human-in-the-loop reproduction as a last resort, and hands off to a separate /improve-codebase-architecture skill when the root cause points to a structural gap like a missing test seam or tangled callers.

Engineers and coding agents debugging hard, non-obvious, or non-deterministic bugs who need a disciplined loop-first process rather than reading code and guessing.