Diagnosing Bugs

Diagnosing Bugs is a disciplined diagnosis loop for hard bugs and performance regressions, adapted from Matt Pocock's skills collection under the MIT license. Phases may be skipped only when that is explicitly justified. When exploring the codebase it reads CONTEXT.md if present and checks architecture decision records in the area being touched. It has six phases.

1. Build a feedback loop. This is the core of the skill: with a tight pass/fail signal that goes red on this bug, the cause will be found, and without one no amount of reading code helps. Options to try, roughly in order: a failing test at the seam that reaches the bug, a curl or HTTP script against a dev server, a CLI invocation diffed against a known-good snapshot, a headless browser script (Playwright or Puppeteer), replaying a captured trace, a throwaway harness with mocked dependencies, a property or fuzz loop of about 1000 random inputs, a bisection harness usable with git bisect run, a differential loop between old and new versions or two configs, and as a last resort a human-in-the-loop script. Then tighten the loop: make it faster, make the signal sharper by asserting the specific symptom, and make it more deterministic by pinning time, seeding random numbers, isolating the filesystem and freezing the network. For non-deterministic bugs the goal is a higher reproduction rate, by looping the trigger 100 times, adding stress and narrowing timing windows. A 50 percent flake is debuggable; 1 percent is not. The phase is complete only when one command, already run with its output shown, is red-capable (asserts the user's exact symptom), deterministic, fast (seconds) and runnable by the agent unattended. If no loop can be built, stop and say so, list what was tried, and ask for access to a reproducing environment, a captured artifact such as a HAR file, log dump, core dump or timestamped screen recording, or permission to add temporary production instrumentation. Do not hypothesize without a loop.
2. Reproduce and minimise. Confirm the loop shows the failure the user described, not a nearby one, and that it reproduces across runs. Then shrink it, cutting inputs, callers, config, data and steps one at a time until every remaining element is load-bearing.
3. Hypothesise. Write 3 to 5 ranked, falsifiable hypotheses in the form "if X is the cause, changing Y will make the bug disappear", and show the ranked list to the user before testing, since they may know about a recent deploy or ruled-out ideas. Proceed with the ranking if the user is away.
4. Instrument. Each probe maps to one prediction and changes one variable at a time. Prefer a debugger or REPL over targeted logs, never "log everything and grep", and tag every debug log with a unique prefix such as [DEBUG-a4f2] so cleanup is a single grep. For performance regressions, establish a baseline measurement (timing harness, performance.now(), profiler or query plan) and bisect: measure first, fix second.
5. Fix and regression test. Write the regression test before the fix, but only at a correct seam that exercises the real bug pattern at the call site. If no correct seam exists, that is itself a finding about the architecture. Otherwise turn the minimised repro into a failing test, watch it fail, apply the fix, watch it pass and re-run the original Phase 1 loop against the un-minimised scenario.
6. Cleanup and post-mortem. Confirm the original repro is gone, the regression test passes or the missing seam is documented, all debug instrumentation is removed, throwaway prototypes are deleted, and the correct hypothesis is stated in the commit or PR message. Then ask what would have prevented the bug, and hand architectural answers to the /improve-codebase-architecture skill after the fix, not before.

Use it when the user says "diagnose" or "debug this", or reports something broken, throwing, failing or slow, especially hard or intermittent bugs and performance regressions. An example request is to investigate a failure, prove the root cause, implement the smallest safe fix and verify it.

Do not treat it as authorization for destructive, production, paid or external-message actions, which need explicit user approval. If the workflow names a required tool, account, API key or local setup, that must exist first. Validate generated artifacts or recommendations against the user's real sources before treating them as final.

Inputs are the bug report or slowdown, access to the code and a way to run it. Outputs are a runnable red-capable loop, a minimised repro, ranked hypotheses, a root cause, a fix with a regression test, and a cleanup checklist with a post-mortem note. The human-in-the-loop template is a Bash script in which the agent runs a loop and the user follows prompts in their terminal; its two helpers show an instruction and wait for Enter, or read an answer into a variable, and captured values are printed as KEY=VALUE for the agent to parse:

set -euo pipefail

step() {
  printf '\n>>> %s\n' "$1"
  read -r -p "    [Enter when done] " _
}

It works with test runners, HTTP clients, headless browsers, debuggers, profilers and git bisect, and hands off to /improve-codebase-architecture. It is used from Claude Code, Codex CLI and Cursor.

It suits engineers and coding agents who chase bugs that resist quick guesses and want a repeatable process that starts with a trustworthy failing signal.