# Diagnosing Bugs

Run a diagnosis loop on hard bugs and performance regressions.

- Repository: https://github.com/mattpocock/skills (309182 stars)
- Category: Engineering
- License: MIT
- Last updated: 2026-11-01
- Runs scripts: yes, review before use

## Install

Claude Code: `npx skills add mattpocock/skills --skill diagnosing-bugs -g -a claude-code -y`
Codex: `npx skills add mattpocock/skills --skill diagnosing-bugs -g -a codex -y`
Cursor: `npx skills add mattpocock/skills --skill diagnosing-bugs -g -a cursor -y`
Gemini CLI: `npx skills add mattpocock/skills --skill diagnosing-bugs -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add mattpocock/skills`

## Description

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

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Diagnosing Bugs

A discipline for hard bugs. Skip phases only when explicitly justified.

When exploring the codebase, read `GLOSSARY.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

The rest: https://github.com/mattpocock/skills/blob/HEAD/skills/engineering/diagnosing-bugs/SKILL.md