Agent skill · Skills for Real Engineers
/diagnosing-bugs A gated debugging loop for hard bugs
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.
Works with
- Claude Code
- Codex
- GitHub Copilot
- Gemini CLI
- Cursor, OpenCode, Windsurf, Amp and others
Used forDebugging
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
- 1Build 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.
- 2Reproduce and minimise
It confirms the loop shows the user's exact failure, then removes inputs and steps until only essential ones remain.
- 3Rank hypotheses
It lists three to five falsifiable explanations, each with a prediction, and shows them to you before testing.
- 4Instrument
It probes one variable at a time with a debugger or tagged logs, or measures a baseline first for performance issues.
- 5Fix 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
Install this skill
It installs with the Skills for Real Engineers pack.
Claude CodeInstalled as a plugin that updates itself by default.
claude plugin install mattpocock-skills@claude-plugins-officialCodexUpdates at startup.
codex plugin marketplace add mattpocock/skills
codex plugin add mattpocock-skills@mattpocockGitHub CopilotWorks in the CLI and VS Code; the README also shows a one-time settings.json entry to enable auto-update.
copilot plugin marketplace add mattpocock/skills
copilot plugin install mattpocock-skills@mattpocockGemini CLIRe-run both commands to update.
gemini skills install https://github.com/mattpocock/skills.git --path skills/engineering
gemini skills install https://github.com/mattpocock/skills.git --path skills/productivityCursor, OpenCode, Windsurf, Amp and othersCopies editable files into your project; update with npx skills@latest update. Use either this or a plugin per agent, not both.
npx skills@latest add mattpocock/skills -a <agent>Commands come from the author’s README; check it for changes before you run them.
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.
More guides from Skills for Real Engineers
/grill-with-docsPlan interviews that build a project glossaryInterviews you about a plan and records agreed terms and decisions as glossary and ADRs.Read the guide →/tddTest-driven development for coding agentsBuilds features or fixes bugs test-first, one failing test and one fix at a time.Read the guide →
Also in this pack
/ask-mattSuggests which skill or workflow in the pack fits your current situation.↗/domain-modelingBuilds and maintains the project's glossary and architecture decision records during design talks.↗/implement-specImplements a whole spec on one branch, running subagents across ready tickets.↗/implementBuilds a piece of work from a spec or tickets, test-first, then reviews it.↗/improve-codebase-architectureScans the codebase for simplification opportunities and presents them as a visual HTML report.↗/prWrites a pull request body with a summary, evidence it works and merge risk.↗/researchAnswers a question from primary sources and saves cited findings as Markdown in the repo.↗/retroReviews a finished coding session and suggests improvements to the agent's environment.↗/setup-matt-pocock-skillsConfigures a repo once with its issue tracker, triage labels and doc locations.↗/to-specTurns what you already discussed into a spec on your issue tracker.↗/to-ticketsSplits a plan or spec into small tickets that state what blocks what.↗/triageMoves issues and outside PRs through triage states and writes agent-ready briefs.↗
Summary by trendhub. The skill itself lives in mattpocock/skills/skills/engineering/diagnosing-bugs by Matt Pocock (MIT); read the full, current text there.