# /diagnosing-bugs: A gated debugging loop for hard bugs

Source: https://trendhub.net/skills/mattpocock-skills/diagnosing-bugs
Skill folder: https://github.com/mattpocock/skills/tree/main/skills/engineering/diagnosing-bugs
Pack: Skills for Real Engineers (https://trendhub.net/skills/mattpocock-skills)
Works with: Claude Code, Codex, GitHub Copilot, Gemini CLI, Cursor, OpenCode, Windsurf, Amp and others

The diagnosing-bugs skill gives a coding agent a fixed sequence for hard bugs and performance regressions: build a fast loop that reproduces the failure, shrink it, rank testable hypotheses, probe one variable at a time, then fix with a regression test. Each phase has exit criteria, which stops the agent from guessing at causes too early.

## When to use it

- Something is broken, throwing or failing and the cause is not obvious.
- A feature has become noticeably slower and you need to find out why.
- A bug is intermittent and earlier attempts to fix it did not hold.

## How it works

1. **Build a feedback loop**: The agent creates one fast, repeatable command, such as a failing test, curl script or browser script, that shows the reported symptom.
2. **Reproduce and minimise**: It confirms the loop shows the user's exact failure, then removes inputs and steps until only essential ones remain.
3. **Rank hypotheses**: It lists three to five falsifiable explanations, each with a prediction, and shows them to you before testing.
4. **Instrument**: It probes one variable at a time with a debugger or tagged logs, or measures a baseline first for performance issues.
5. **Fix and clean up**: It writes a regression test at a suitable seam, applies the fix, re-runs the original loop and removes debug code.

## What it steers the agent away from

- Reading code and theorizing before the bug can be reproduced
- Fixing a nearby failure instead of the one the user reported
- Leaving stray debug logs and throwaway harnesses in the codebase

## What it can touch

Reads and edits repository files, runs shell commands such as tests, curl requests against a dev server, headless browser scripts and git bisect, and adds temporary tagged logs it later removes. It is told to redact secrets from any output it shows.

## Pairs well with

- `/tdd`
- `/codebase-design`
- `/prototype`
- `/code-review`

## Questions

### What if the bug cannot be reproduced?

The skill tells the agent to stop, list what it tried and ask you for environment access, a redacted log or trace, or permission to add temporary instrumentation.

### Does it handle performance problems?

Yes. For regressions it measures a baseline with timers, a profiler or query plans and bisects, rather than relying on logs.
