diagnosing-bugs Skill for Claude Code: A Six-Phase Debugging Loop

Makes Claude build a fast pass/fail check for a hard bug or slow code first, then reproduce, hypothesise, instrument, fix and clean up in order.

Installs: 876.4K; on skills.sh
Stars: 309.2K; on GitHub
Files: 2; besides SKILL.md
Updated: Nov 2026; last repo commit

diagnosing-bugs stops the agent from guessing. It must first build a feedback loop: a command that goes red on your exact bug, runs in seconds and gives the same answer each time. Only then does it move on to reproducing and shrinking the bug, ranking three to five testable hypotheses, adding tagged debug logs, and fixing.

It triggers when you say "diagnose" or "debug this", or report something broken, throwing, failing or slow. It runs your tests, scripts and commands while it works. It tells the agent to replace secrets with <REDACTED> before showing output.

Good for

Developers stuck on a bug that other prompts could not crack
Anyone chasing a flaky bug or a performance regression
Teams that want debug logs and prototypes cleaned up afterwards

Install diagnosing-bugs

Claude Code

Copy this prompt.

Install the diagnosing-bugs skill in Claude Code. Run this command:

npx skills add https://github.com/mattpocock/skills --skill diagnosing-bugs

Then check that it loaded and tell me how to use it.

2
Paste it into Claude Code. It shows the change and asks before running it.

Requires Node.js.

From its listing on skills.sh. Source.

What's in the skill

When it loads

Diagnosis loop for hard bugs and performance regressions. Use when the user says "diagnose"/"debug this", or reports something broken/throwing/failing/slow.

Sections in SKILL.md

Redact
Phase 1: Build a feedback loop
Ways to construct one, in roughly this order
Tighten the loop
Non-deterministic bugs
When you genuinely cannot build a loop
Completion criterion: a tight loop that goes red
Phase 2: Reproduce + minimise
Minimise
Phase 3: Hypothesise
Phase 4: Instrument
Phase 5: Fix + regression test
Phase 6: Cleanup

Key facts

Author: Matt Pocock
Repo: mattpocock/skills
Installs on skills.sh: 876,433 (Nov 2, 2026)
GitHub stars: 309,237 (Nov 2, 2026)
License: MIT
Last repo commit: Nov 1, 2026
Files next to SKILL.md: 2 files
skills.sh audits: Gen Agent Trust Hub pass, Socket pass, Snyk pass
Bundled script: scripts/hitl-loop.template.sh, a template for loops that need a human to click

What it includes

Create one fast, repeatable command that fails on this exact bug
The SKILL.md lists ten ways, from a failing test to curl scripts, headless browser scripts, replaying a captured trace and git bisect.
Runs code · Phase 1: Build a feedback loop
Confirm the loop shows your symptom, then cut it down to the smallest red case
Runs code · Phase 2: Reproduce and minimise
Write 3 to 5 ranked, testable guesses and show them to you first
Phase 3: Hypothesise
Add one probe per hypothesis, with logs tagged like [DEBUG-a4f2]
Write · Phase 4: Instrument
Write the failing test, watch it fail, fix, watch it pass
Runs code · Phase 5: Fix and regression test
Re-run the loop, remove tagged logs and throwaway prototypes
Delete · Phase 6: Cleanup
Template that walks you through steps only a human can do and captures the result
Runs code · scripts/hitl-loop.template.sh
Replace every secret with <REDACTED> in anything it shows
Redact rule

From the official docs

Permissions

Medium risk

What it can do

Read your data
Create and change things
Delete things
Read-only mode

Watch out for

It runs commands and scripts on your machine
Use a dev or test environment. Read each command before approving it, and avoid pointing loops at production. github.com
It adds temporary debug logs to your code
Every log carries a unique [DEBUG-...] tag. Search for that prefix at the end to confirm all are gone before you commit. github.com
Redaction is an instruction, not a filter
The skill asks the agent to write <REDACTED> for secrets. Do not rely on it alone to keep credentials out of logs. github.com

Technical details

Talks to	Whatever your own curl, test or browser scripts call
Scopes	Your source code Output of commands it runs Logs and captured request data you let it read

Questions

What does diagnosing-bugs do?

It forces a debugging order: build a red-capable check first, reproduce and shrink, rank hypotheses, instrument, fix with a regression test, then clean up. It says that skipping the loop and theorising is the failure it prevents.

How do I install diagnosing-bugs?

Use the install box at the top. It has one SKILL.md and one template script, and the SKILL.md only reads GLOSSARY.md and ADRs if your repo has them.

When does it start?

When you say "diagnose" or "debug this", or report that something is broken, failing, throwing or slow.

Does it run commands on my machine?

Yes. It runs tests, curl calls, scripts and possibly git bisect to get its feedback loop, and it adds debug logs to your code. Watch what it runs, and keep it off production systems.

Does it leak my secrets?

The SKILL.md tells the agent to write <REDACTED> in place of every secret in shown output, and to build loops against environment variables. That is an instruction to the model, so still keep real credentials out of the folder you debug in.

How is it different from tdd?

The README describes tdd as building features or fixing bugs one vertical slice at a time. diagnosing-bugs is for hard bugs and performance regressions, and its SKILL.md puts most of the effort into building a repeatable failing check before any fix.

Information

updated Nov 2, 2026

Repository: mattpocock/skills
Folder: skills/engineering/diagnosing-bugs

mattpocock/skills skills.sh

Sources

Docs, issue trackers and discussions this page is built from.

Show all 3

diagnosing-bugs SKILL.md · github.com
diagnosing-bugs on skills.sh · skills.sh
mattpocock/skills README · github.com