Skip to content
SkillModel-led1,994 tokens in use

Diagnosing Bugs

A six-phase debugging discipline that starts by building a tight, red-capable feedback loop for the bug before any theorising.

328,754 stars on the repository MIT Licensemattpocock/skills · skills/engineering/diagnosing-bugs
claude plugin install mattpocock-skills@claude-plugins-official
View source

Install command as written in the repository's README

Skill label

measured from its files

What installing Diagnosing Bugs costs

43tokens idle
1,994tokens in use

Idle is what sits in context while the skill is installed. In use is its instructions, loaded when it runs. Counts are approximate, made offline with cl100k_base.

Model dependence Model-led

Script-ledMixedModel-led

Mostly instructions, so how well it works depends on the model that follows them.

This describes the skill's structure, how much of it is scripts. It does not say how well it works. Scripts: scripts/hitl-loop.template.sh.

Touches

shelldetected

Declared tags come from the skill's frontmatter; detected ones from its scripts and code blocks. This is detected, not audited.

How it scores

Quality

How well the skill is written, counted from its own files: its frontmatter, its steps, examples, stated output and constraints, its size and whether every file it ships is one it names.How we score it →
Good
  • Frontmatter12/15
  • Structure19/25
  • Examples0/15
  • Output15/15
  • Size15/15
  • Resources7/15

Security

Starts at 100 and loses points for each thing in the skill's files that a reader should look at first.How we score it →
Excellent
  • Runs shell commands−5

    does this on the machine, and the frontmatter does not say so

    scripts/hitl-loop.template.sh, line 18

Repository health

Pre-computed score based on development activity, maintenance, community, maturity, and trend momentum.How we score it →
Excellent
  • Development activity96
  • Maintenance100
  • Community56
  • Maturity32
  • Momentum40

Diagnosing Bugs is for hard bugs and performance regressions. Phase 1 builds a feedback loop, a single command that goes red on this exact bug, and the skill states that no theorising may start before that command exists. The next phases reproduce and minimise, hypothesise, instrument, fix with a regression test, and clean up.

It triggers when the user says diagnose or debug this, or reports something broken, throwing, failing or slow.

What You Get

  • A loop that is red-capable, deterministic, fast and runnable by the agent without supervision
  • A minimised repro in which every remaining element is load-bearing
  • Three to five ranked, falsifiable hypotheses shown to you before any is tested
  • A regression test written before the fix at a correct seam, or a note that no correct seam exists
  • A cleanup checklist that removes tagged debug logs and states the confirmed hypothesis in the commit message

Common Use Cases

  • Chasing an intermittent flake by raising its reproduction rate
  • Finding which commit introduced a regression by automating a bisection run
  • Measuring a performance regression against a baseline before changing anything

What Makes It Unique

The skill treats the feedback loop as the whole job and says the rest is mechanical. It forbids hypothesising without a loop, asks you to review the ranked hypotheses at a cheap checkpoint, tags every debug log with a unique prefix so cleanup is one grep, and treats a missing test seam as a finding about the architecture.

Under The Hood

The skill is Markdown instructions plus a bash template, scripts/hitl-loop.template.sh. The template defines a step helper that waits for Enter and a capture helper that reads an answer into a variable, then prints the captured values as KEY=VALUE for the agent to parse. The skill tells the model to run commands, tests, curl requests, debuggers and git bisect, and to redact secrets before showing any output. It also reads GLOSSARY.md and ADRs when they exist.

Join founders building with open source

Opinionated takes, migration guides, cost-saving tips, and insights from the open source ecosystem.

Subscribe on SubstackJoin 750+ subscribers