Question 1

What does the diagnosing-bugs skill actually do?

Accepted Answer

It runs a six-phase discipline for hard bugs and performance regressions: redact secrets, build a feedback loop, reproduce and minimise, rank hypotheses, instrument, then fix with a regression test and clean up. The skill triggers whenever you say 'diagnose' or 'debug this', or report something broken, throwing, failing, or slow. Phases can be skipped only with explicit justification — the whole point is stopping the agent from guessing.

Question 2

Why does it demand a feedback loop before any hypothesis?

Accepted Answer

Because that phase is the skill — everything else is mechanical. A tight pass/fail signal that goes red on the actual bug makes the cause findable through bisection, hypothesis-testing, and instrumentation. Without that signal, no amount of staring at code saves you. The SKILL.md is blunt: if you catch yourself reading code to build a theory before a red-capable command exists, stop — jumping straight to a hypothesis is the exact failure this skill prevents.

Question 3

What counts as a tight, red-capable loop?

Accepted Answer

One command you have already run at least once — a test invocation, script path, or curl — that drives the real bug code path and asserts the user's exact symptom, so it can go red on this bug and green once fixed. It must be deterministic (same verdict every run), fast (seconds, not minutes), and agent-runnable without a human. A 30-second flaky loop is barely better than no loop; a 2-second deterministic one is a debugging superpower.

Question 4

How do you handle flaky, non-deterministic bugs?

Accepted Answer

You don't chase a clean repro — you raise the reproduction rate. Loop the trigger a hundred times, parallelise, add stress, narrow timing windows, inject sleeps. The skill's rule of thumb: a 50%-flake bug is debuggable, a 1% bug is not. Keep raising the rate until the bug is debuggable, then proceed.

Question 5

What happens when a loop genuinely can't be built?

Accepted Answer

The agent stops and says so explicitly, listing what it tried, then asks for one of three things: access to the environment that reproduces it, a redacted captured artifact (HAR file, log dump, core dump, timestamped screen recording), or permission to add temporary production instrumentation. The rule is absolute: without a loop, no hypothesising.

Question 6

Why show the ranked hypotheses to the user?

Accepted Answer

The skill generates 3–5 falsifiable hypotheses before testing any of them, because single-hypothesis generation anchors on the first plausible idea. Each must state a prediction — if X is the cause, changing Y makes the bug disappear or worse. Showing the ranked list before testing costs little and saves hours, since users often re-rank instantly with domain knowledge like 'we just deployed a change to number three'.

Question 7

How does the skill keep instrumentation honest?

Accepted Answer

Change one variable at a time, and prefer a debugger or REPL inspection over logs — one breakpoint beats ten log statements. Targeted logs go only at the boundaries that distinguish hypotheses, never 'log everything and grep'. Every debug log gets a unique prefix like [DEBUG-a4f2], so cleanup at the end is a single grep. For performance regressions, logs are usually wrong: establish a baseline measurement first, then bisect.

Question 8

When should the regression test actually be written?

Accepted Answer

Before the fix, but only if a correct seam exists — one where the test exercises the real bug pattern as it occurs at the call site. If the only available seam is too shallow, a regression test there gives false confidence. Crucially, if no correct seam exists, that itself is the finding: the codebase architecture is preventing the bug from being locked down, and that gets flagged.

Question 9

What does the completion checklist look like?

Accepted Answer

Six things: the original repro no longer reproduces (re-run the Phase 1 loop), the regression test passes, all [DEBUG-...] instrumentation is removed by grepping its prefix, throwaway prototypes are deleted or moved to a marked location, and the hypothesis that turned out correct is stated in the commit or PR message so the next debugger learns from it.

Question 10

Why the redaction step at the very start?

Accepted Answer

The skill has the agent show commands, outputs, and captured artifacts, so secrets get redacted first — written as <REDACTED> — and loops are built against environment variables so credentials stay in the environment, not the transcript. Captured artifacts carry auth headers, so only the lines carrying the signal get quoted. If redacted output isn't enough to diagnose, the agent says so and asks for more.

Engineering on Top AI Skills

My Spec Session With to-Spec: No Interview, Just Synthesis

Implement Skill: A 7-Line Spec That Routes AI Coding Work

Codebase Design Skill: Deep Modules That Earn Their Interface

The Vocabulary: Precision Is the Feature

Diagnosing Bugs Skill FAQ: The Feedback Loop Comes First

Frequently Asked Questions

Why a Diagnosing Bugs FAQ Exists

Code Review Skill: Two-Axis Review That Keeps Standards and Spec Honest

Setup Matt Pocock's Skills: Prepare Your Repo for AI Agents