diagnose
Disciplined diagnosis loop for hard bugs and performance regressions. Reproduce → minimise → hypothesise → instrument → fix → regression-test. Use when user says "diagnose this" / "debug this", reports a bug, says something is broken/throwing/failing, or describes a performance regression.
Best for hard bugsWorks with GitHubLow risk
⌘source
- author
@mattpocock- language
- Shell
★36kstars
2.9kforks
Apr 29, 2026
✦overview.md
Key Features
- ·Build a fast, deterministic feedback loop
- ·Reproduce, minimise, hypothesise, instrument, fix, regression-test
- ·Multiple feedback loop construction strategies
- ·Use domain glossary and ADRs for context
Use Cases
- →Debugging a hard-to-reproduce bug in production
- →Investigating a performance regression after a deployment
- →Diagnosing a test failure that only occurs intermittently
- →Tracking down a bug reported by a user with minimal reproduction steps
Best for
- ✓hard bugs
- ✓performance regressions
- ✓intermittent failures
Not ideal for
- !simple syntax errors
- !trivial logic mistakes
- !greenfield development without bugs
FAQs
name
diagnose
description
Disciplined diagnosis loop for hard bugs and performance regressions. Reproduce → minimise → hypothesise → instrument → fix → regression-test. Use when user says "diagnose this" / "debug this", reports a bug, says something is broken/throwing/failing, or describes a performance regression.
Diagnose
A discipline for hard bugs. Skip phases only when explicitly justified.
When exploring the codebase, use the project's domain glossary to get a clear mental model of the relevant modules, and check ADRs in the area you're touching.
Phase 1 — Build a feedback loop
This is the skill. Everything else is mechanical. If you have a fast, deterministic, agent-runnable pass/fail signal for the bug, you will find the cause — bisection, hypothesis-testing, and instrumentation all just consume that signal. 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 — try them in roughly this order
- Failing test at whatever seam reaches the bug — unit, integration, e2e.
- Curl / HTTP script against a running dev server.
- CLI invocation with a fixture input, diffing stdout against a known-good snapshot.
- Headless browser script (Playwright / Puppeteer) — drives the UI, asserts on DOM/console/network.
$install
1-click copynpx skills add mattpocock/skills --skill diagnoseSafety assessment
★
Clarity score
How clear and easy to understand the SKILL.md instructions are, rated from 1 to 5.
4/ 5
very goodClear and well structured, with only minor parts that might need a second read.
◎
Actionability score
How directly an agent can act on the SKILL.md instructions, rated from 1 to 5.
4/ 5
highMostly actionable with clear steps; only a few small gaps remain.