Diagnosing hard bugs

Diagnoses hard bugs and slowdowns by first building a fast, deterministic command that reproduces the exact symptom, then minimising it, ranking falsifiable hypotheses and adding a regression test at a real seam. Use when something fails, throws or got slow.

DebuggingPack: Matt Pocock's skills138 linesdiagnosing-bugs
Author
Source
mattpocock/skills/skills/engineering/diagnosing-bugs @ abeeaf9
License
MIT · Copyright (c) 2026 Matt Pocock

About this skill

What it does

Diagnosing bugs is a six-phase loop for hard bugs and performance regressions, with most of the weight on phase one: build a feedback loop before forming any theory. The loop is one command, already run and shown to you, that goes red on your exact symptom, is deterministic, takes seconds and can be run by the agent alone. Ten ways to build one are listed, from a failing test or a curl script to a git bisect run harness. Flaky bugs need a higher reproduction rate, not a clean repro. With no loop the agent stops and asks for access, a redacted capture or permission to instrument production.

Then it shrinks the repro until every part is load-bearing, shows you 3–5 ranked, falsifiable hypotheses before testing, and probes one variable at a time: debugger first, logs tagged like [DEBUG-a4f2], a baseline measurement for slowness. The regression test comes before the fix, but only at a seam that reproduces the real call pattern; a missing seam is reported as an architecture finding. Cleanup removes the tagged logs, and the commit message names the hypothesis that held. Secrets in anything shown become <REDACTED>.

scripts/hitl-loop.template.sh is the last resort when a person must click through: step waits for Enter, capture stores an answer, and the values come back as KEY=VALUE. agents/openai.yaml holds the Codex display name and description.

When to use it, and when not

Use it when something is broken, failing or slow and the cause is not obvious, flaky failures included.

Skip it for a typo the compiler points at, or when you only want a quick guess: without a loop the skill will not hypothesise.

How to run it

The install command below puts the whole folder in place. The agent picks the skill up by its description when you report a failure or say "diagnose"; to call it yourself:

  • Claude Code: /diagnosing-bugs, or ask for the skill by name.
  • Codex: $diagnosing-bugs.
  • Cursor: type / in the Agent chat and pick diagnosing-bugs.

Example: /diagnosing-bugs The /export endpoint got three times slower after last week's release. Build a timing loop first.

It calls no other skill but reads GLOSSARY.md and ADRs if domain-modeling has written them. The template needs bash (Git Bash on Windows).

How it differs from similar skills

Systematic debugging and our Root-cause debugging also reproduce first, then test one hypothesis at a time. Diagnosing bugs demands more of the repro — a fast, deterministic command already run — ranks several hypotheses at once for you to reorder, and adds a performance branch, redaction and the seam check. Debugging and error recovery is a stop-the-line triage checklist with patterns per failure type. Git bisect for regressions from our catalog details the bisection harness this skill lists as one way to build the loop: git bisect run exit codes, skipping commits that do not build, repeats for flaky tests. Performance optimization goes further than this skill's short performance branch: a baseline, one proven bottleneck at a time, re-measuring against noise and reverting what does not help.

Install

Run one command — it saves SKILL.md and the files it uses into your agent's skills folder. Claude Code and Codex pick up a new skill without a restart; if it does not show up, restart the agent.

Claude Code — macOS, Linux
curl -fsSL --create-dirs -o ~/.claude/skills/diagnosing-bugs/SKILL.md https://anymodel.org/en/skills/matt-pocock/diagnosing-bugs/SKILL.md -o ~/.claude/skills/diagnosing-bugs/LICENSE https://anymodel.org/en/skills/matt-pocock/diagnosing-bugs/LICENSE -o ~/.claude/skills/diagnosing-bugs/agents/openai.yaml https://anymodel.org/en/skills/matt-pocock/diagnosing-bugs/agents/openai.yaml -o ~/.claude/skills/diagnosing-bugs/scripts/hitl-loop.template.sh https://anymodel.org/en/skills/matt-pocock/diagnosing-bugs/scripts/hitl-loop.template.sh
Codex, Cursor — macOS, Linux
curl -fsSL --create-dirs -o ~/.agents/skills/diagnosing-bugs/SKILL.md https://anymodel.org/en/skills/matt-pocock/diagnosing-bugs/SKILL.md -o ~/.agents/skills/diagnosing-bugs/LICENSE https://anymodel.org/en/skills/matt-pocock/diagnosing-bugs/LICENSE -o ~/.agents/skills/diagnosing-bugs/agents/openai.yaml https://anymodel.org/en/skills/matt-pocock/diagnosing-bugs/agents/openai.yaml -o ~/.agents/skills/diagnosing-bugs/scripts/hitl-loop.template.sh https://anymodel.org/en/skills/matt-pocock/diagnosing-bugs/scripts/hitl-loop.template.sh
Claude Code — Windows PowerShell
foreach ($f in 'SKILL.md','LICENSE','agents/openai.yaml','scripts/hitl-loop.template.sh') { $p = Join-Path "$HOME\.claude\skills\diagnosing-bugs" $f; New-Item -ItemType Directory -Force (Split-Path $p) | Out-Null; Invoke-WebRequest "https://anymodel.org/en/skills/matt-pocock/diagnosing-bugs/$f" -UseBasicParsing -OutFile $p }
Codex, Cursor — Windows PowerShell
foreach ($f in 'SKILL.md','LICENSE','agents/openai.yaml','scripts/hitl-loop.template.sh') { $p = Join-Path "$HOME\.agents\skills\diagnosing-bugs" $f; New-Item -ItemType Directory -Force (Split-Path $p) | Out-Null; Invoke-WebRequest "https://anymodel.org/en/skills/matt-pocock/diagnosing-bugs/$f" -UseBasicParsing -OutFile $p }

Any other agent: save the file into its skills folder, or give it the link to the file: https://anymodel.org/en/skills/matt-pocock/diagnosing-bugs/SKILL.md

SKILL.md

Raw

Diagnosing Bugs

A discipline for hard bugs. Skip phases only when explicitly justified.

When exploring the codebase, read GLOSSARY.md (if it exists) to get a clear mental model of the relevant modules, and check ADRs in the area you're touching.

Redact

This skill has you show commands, outputs and captured artifacts. Redact every secret first: write <REDACTED> in its place. Build loops against env vars, so the credential stays in the environment rather than in what you show. Captured artifacts carry auth headers: quote only the lines that carry the signal.

If the redacted output is not enough to diagnose the bug, say so and ask the user.

Phase 1: Build a feedback loop

This is the skill. Everything else is mechanical. If you have a tight pass/fail signal for the bug (one that goes red on this bug), you will find the cause; bisection, hypothesis-testing, and instrumentation all just consume it. If you don't have one, no amount of staring at code will save you.

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

Ways to construct one, in roughly this order

  1. Failing test at whatever seam reaches the bug: unit, integration, 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) that drives the UI and asserts on DOM/console/network.
  5. Replay a captured trace. Save a real network request / payload / event log to disk; replay it through the code path in isolation.
  6. Throwaway harness. Spin up a minimal subset of the system (one service, mocked deps) that exercises the bug code path with a single function call.
  7. Property / fuzz loop. If the bug is "sometimes wrong output", run 1000 random inputs and look for the failure mode.
  8. Bisection harness. If the bug appeared between two known states (commit, dataset, version), automate "boot at state X, check, repeat" so you can git bisect run it.
  9. Differential loop. Run the same input through old-version vs new-version (or two configs) and diff outputs.
  10. HITL bash script. Last resort. If a human must click, drive them with scripts/hitl-loop.template.sh so the loop is still structured. Captured output feeds back to you.

Build the right feedback loop, and the bug is 90% fixed.

Tighten the loop

Treat the loop as a product. Once you have a loop, tighten it:

  • Can I make it faster? (Cache setup, skip unrelated init, narrow the test scope.)
  • Can I make the signal sharper? (Assert on the specific symptom, not "didn't crash".)
  • Can I make it 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 one is tight, a debugging superpower.

Non-deterministic bugs

The goal is not a clean repro but a higher reproduction rate. Loop the trigger 100×, parallelise, add stress, narrow timing windows, inject sleeps. A 50%-flake bug is debuggable; 1% is not, so keep raising the rate until it's debuggable.

When you genuinely cannot build a loop

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

Completion criterion: a tight loop that goes red

Phase 1 is done when the loop is tight and red-capable: you can name one command (a script path, a test invocation, a curl) that you have already run at least once (show the invocation and its output, redacted), and that is:

  • Red-capable: it drives the actual bug code path and asserts the user's exact symptom, so it can go red on this bug and green once fixed. Not "runs without erroring"; it must be able to catch this specific bug.
  • Deterministic: same verdict every run (flaky bugs: a pinned, high reproduction rate, per above).
  • Fast: seconds, not minutes.
  • Agent-runnable: you can run it unattended; a human in the loop only via scripts/hitl-loop.template.sh.

If you catch yourself reading code to build a theory before this command exists, stop: jumping straight to a hypothesis is the exact failure this skill prevents. No red-capable command, no Phase 2.

Phase 2: Reproduce + minimise

Run the loop. Watch it go red as the bug appears.

Confirm:

  • The loop produces the failure mode the user described, not a different failure that happens to be nearby. Wrong bug = wrong fix.
  • The failure is reproducible across multiple runs (or, for non-deterministic bugs, reproducible at a high enough rate to debug against).
  • You have captured the exact symptom (error message, wrong output, slow timing) so later phases can verify the fix actually addresses it.

Minimise

Once it's red, shrink the repro to the smallest scenario that still goes red. Cut inputs, callers, config, data, and steps one at a time, re-running the loop after each cut, and keep only what's load-bearing for the failure.

Why bother: a minimal repro shrinks the hypothesis space in Phase 3 (fewer moving parts left to suspect) and becomes the clean regression test in Phase 5.

Done when every remaining element is load-bearing: removing any one of them makes the loop go green.

Do not proceed until you have reproduced and minimised.

Phase 3: Hypothesise

Generate 3–5 ranked hypotheses before testing any of them. Single-hypothesis generation anchors on the first plausible idea.

Each hypothesis must be falsifiable: state the prediction it makes.

Format: "If <X> is the cause, then <changing Y> will make the bug disappear / <changing Z> will make it worse."

If you cannot state the prediction, the hypothesis is a vibe: discard or sharpen it.

Show the ranked list to the user before testing. They often have domain knowledge that re-ranks instantly ("we just deployed a change to #3"), or know hypotheses they've already ruled out. Cheap checkpoint, big time saver. Don't block on it; proceed with your ranking if the user is AFK.

Phase 4: Instrument

Each probe must map to a specific prediction from Phase 3. Change one variable at a time.

Tool preference:

  1. Debugger / REPL inspection if the env supports it. One breakpoint beats ten logs.
  2. Targeted logs at the boundaries that distinguish hypotheses.
  3. Never "log everything and grep".

Tag every debug log with a unique prefix, e.g. [DEBUG-a4f2]. Cleanup at the end becomes a single grep. Untagged logs survive; tagged logs die.

Perf branch. For performance regressions, logs are usually wrong. Instead: establish a baseline measurement (timing harness, performance.now(), profiler, query plan), then bisect. Measure first, fix second.

Phase 5: Fix + regression test

Write the regression test before the fix, but only if there is a correct seam for it.

A correct seam is one where the test exercises the real bug pattern as it occurs at the call site. If the only available seam is too shallow (single-caller test when the bug needs multiple callers, unit test that can't replicate the chain that triggered the bug), a regression test there gives false confidence.

If no correct seam exists, that itself is the finding. Note it. The codebase architecture is preventing the bug from being locked down. Flag this for the next phase.

If a correct seam exists:

  1. Turn the minimised repro into a failing test at that seam.
  2. Watch it fail. If you forced the red by mutating code or a fixture, diff against a pristine copy to prove the mutation landed before you trust it.
  3. Apply the fix.
  4. Watch it pass.
  5. Re-run the Phase 1 feedback loop against the original (un-minimised) scenario.

Phase 6: Cleanup

Required before declaring done:

  • Original repro no longer reproduces (re-run the Phase 1 loop)
  • Regression test passes (or absence of seam is documented)
  • All [DEBUG-...] instrumentation removed (grep the prefix)
  • Throwaway prototypes deleted (or moved to a clearly-marked debug location)
  • The hypothesis that turned out correct is stated in the commit / PR message, so the next debugger learns

Connect through AnyModel API

This skill runs on whatever model your agent uses. Point Claude Code, Codex or Cursor at AnyModel to run it on Claude, GPT, Gemini and more with one key — pay per token, no subscription.

More from the pack Matt Pocock's skills

Code review against standards and spec

Reviews the diff since a commit, branch or tag on two axes in parallel subagents: the repo's written standards plus a baseline of Fowler code smells, and the originating spec or issue. Use when a branch or PR needs checking against its spec.

Deep module design

Fixes a shared vocabulary for deep modules (interface, seam, adapter, depth, leverage), with the deletion test, dependency categories and a design-it-twice pattern on parallel subagents. Use when designing a module's interface or deciding where a seam goes.

Domain modeling

Sharpens a project's domain language during design: challenges fuzzy or conflicting terms, writes resolved ones to GLOSSARY.md at once and offers a short ADR only for hard-to-reverse trade-offs. Use when discussing terminology or recording an ADR.

Implement a spec

Implements a spec and its tickets on one integration branch: a fresh implementer subagent per ticket in its own worktree, run in parallel along the blocking graph, then a code review and one fix pass. Use when the tickets from to-tickets are ready.

Improve codebase architecture

Finds shallow modules worth deepening, starting from the code that changes most, shows the candidates in an HTML report with before/after diagrams and grills the chosen one with you. Use when a codebase has grown hard to test or navigate.

Throwaway prototype

Builds throwaway code to answer one design question: a single-file clickable HTML demo for a state model, or several structurally different UI variants on one route switched by a URL param. Use when checking whether logic holds or how a page should look.

Coding session retrospective

Reviews a finished coding session from its logs and proposes changes to the agent's environment: navigation pointers, lint rules, pre-commit and CI checks, reviewer standards, tool use. Use when an agent session went slowly or made avoidable mistakes.

TDD with integration tests

Drives test-first work through public interfaces: agrees the seams to test with the user, runs one red-green cycle per test, mocks only at system boundaries and leaves refactoring to review. Use when building a feature or fixing a bug test-first.

Conversation to spec

Turns the current conversation and codebase into a spec with user stories, implementation and testing decisions, and publishes it to the issue tracker as ready-for-agent, without interviewing the user. Use when a discussed feature needs writing up.

Spec to tickets

Splits a spec, plan or conversation into tracer-bullet tickets, vertical slices that each fit one agent session, with blocking edges, and publishes them as local files or tracker issues. Use when work is too big for one session and needs a task graph.

Issue and PR triage

Triages issues and external PRs on the tracker: gives each a category and a state, checks for existing code and past rejections, reproduces bugs and writes agent briefs for ready work. Use when a maintainer works through incoming issues and PRs.

Wayfinder for huge work

Charts work too big for one agent session as a map issue with child decision tickets on the tracker, then resolves one ticket per session until the route to the goal is clear. Use when a large effort has open questions that block a spec or plan.

Bash wizard for manual steps

Generates an interactive bash script that walks a person through manual steps such as dashboard setup, API keys and CI secrets, opening each URL and saving values to .env and GitHub secrets. Use when setup or a migration needs steps only a human can take.

Git guardrails for Claude Code

Installs a Claude Code PreToolUse hook that stops the usual forms of git push, reset --hard, clean -f, branch -D and checkout or restore of the whole tree, for one project or all, then tests it. Use when you want a safety net against an agent pushing or discarding work on its own.

Migrate tests to shoehorn

Replaces as and as unknown as casts in TypeScript tests with fromPartial and fromAny from @total-typescript/shoehorn, adds the imports and runs the type check. Use when tests fake whole objects or cast partial test data to satisfy the compiler.

Pre-commit hooks setup

Sets up Husky and lint-staged in a Node repo so each commit runs Prettier on staged files, then the typecheck and test scripts, matched to the lockfile, and makes the first commit through the hook. Use when a repo has no commit-time checks.

Grilling a plan

Questions the user about a plan or decision in rounds of numbered questions with recommended answers, looks facts up itself through subagents and stops only when no decision is left assumed. Use when a plan needs stress-testing before work starts.

Teach me a topic

Runs a multi-session course in the current folder: a mission, trusted sources, short HTML lessons with quizzes, reference sheets and learning records that set the next lesson. Use when the user wants to learn a topic over time, not get one answer.

Decision questionnaire

Writes a Markdown questionnaire for someone who holds knowledge the user lacks, after asking only who it goes to and what answers are needed, with the most important questions first. Use when a decision depends on facts from another person.

Writing for agents

Gives the rules for writing text agents read: skill descriptions as context pointers, what to keep inline and what to move to a separate file, completion criteria, leading words and pruning. Use when creating or editing a skill, AGENTS.md or CLAUDE.md.