Agent skill · software engineering · mattpocock
diagnosing-bugs
Diagnosis loop for hard bugs and performance regressions. Use when the user says "diagnose"/"debug this", or reports something broken/throwing/failing/slow.
Why this skill is useful
Provides a structured approach to diagnosing bugs with specific commands and techniques that the AI wouldn't reliably generate on its own.
What it needs
Requires curl, playwright, puppeteer installed locally. About 6k tokens when loaded. Last updated 2026-08-06. 207,363 stars on the source repository.
What this skill does
Diagnosing Bugs A discipline for hard bugs. Skip phases only when explicitly justified. When exploring the codebase, read CONTEXT.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. …
How to use it
Reference it in AdaL, Claude Code, Cursor or any coding agent — nothing to install:
@skills mattpocock/diagnosing-bugs