diagnosing-bugs
Diagnosis loop for hard bugs and performance regressions. Use when the user says "diagnose"/"debug this", or reports something broken/throwing/failing/slow.
- Kind
- Skill
- Works with
- Claude Code
- Source
- mattpocock/skills @ 24fe0ef7737e
- Path
- skills/engineering/diagnosing-bugs/SKILL.md
- License
- MIT
- Jobs
- Debugging
InstallCopy it from the source repository, or sign in and let the assistant adapt it for your project.
# 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 …