TESTING AND RELIABILITY / Matt Pocock
Diagnosing Bugs
A debugging procedure that establishes a reproducible symptom, tests competing explanations and preserves a regression check.
“Diagnosis loop for hard bugs and performance regressions. Use when the user says "diagnose"/"debug this", or reports something broken/throwing/failing/slow.”
01 / THE REASONING
Why this made the selection.
- Requires a red-capable reproduction before edits, so an apparent improvement has a concrete behavior to compare against.
- Tests one hypothesis at a time and asks for the original scenario to be rerun after the fix, including removal of temporary instrumentation.
02 / THE REVIEW RECORD
What we actually inspected.
Source review has boundaries.
A clear record is more useful than a “safe” badge.
Material inspected
- skills/engineering/diagnosing-bugs/SKILL.md
- README.md (installation and supported-host sections)
- LICENSE
- skills/engineering/diagnosing-bugs/agents/openai.yaml
- skills/engineering/diagnosing-bugs/scripts/hitl-loop.template.sh
Our findings
- The definition distinguishes observations from hypotheses and ties each proposed mechanism to a falsification test.
- The full HITL helper was inspected: it prints user-supplied answers and needs adaptation to the real scenario.
Not established by this review
- No upstream definition, helper, installer or generated workload was executed.
- No end-to-end agent session or effectiveness benchmark was run.
The review applies to the material and revision named here. A newer upstream release can change its behavior.
03 / PUT IT TO WORK
Add a skill to your workflow.
DOCUMENTED COMMAND
npx skills add https://github.com/mattpocock/skills/tree/c55ee46073ed923f86ce59a5eb3b6d895095d1b7/skills/engineering/diagnosing-bugs --skill diagnosing-bugsCopying does not execute this command. It may retrieve a newer version than the reviewed source.
- Install the complete skill directory, including its references and helpers; select your intended host and project scope.
- Review the instructions before invoking them. The source revision is pinned; the installer was not executed or version-pinned by this review.
Before you start
- Node.js/npm and git for the documented Skills installer
- An agent host that supports the skill format and the tools required by the workflow
04 / FOLLOW THE EVIDENCE
The source trail.
Our notes are separate from the original resource.
Check upstream before adopting a new version.
https://github.com/mattpocock/skills/blob/c55ee46073ed923f86ce59a5eb3b6d895095d1b7/skills/engineering/diagnosing-bugs/SKILL.md
Supports: summary, upstreamDescription, whySelected, bestFor, limitations, review, access
https://github.com/mattpocock/skills/blob/c55ee46073ed923f86ce59a5eb3b6d895095d1b7/README.md
Supports: install, compatibility
https://github.com/mattpocock/skills/blob/c55ee46073ed923f86ce59a5eb3b6d895095d1b7/LICENSE
Supports: license, access.cost
https://github.com/mattpocock/skills/blob/c55ee46073ed923f86ce59a5eb3b6d895095d1b7/skills/engineering/diagnosing-bugs/agents/openai.yaml
Supports: review, limitations, install, access
https://github.com/mattpocock/skills/blob/c55ee46073ed923f86ce59a5eb3b6d895095d1b7/skills/engineering/diagnosing-bugs/scripts/hitl-loop.template.sh
Supports: review, limitations, install, access
https://github.com/vercel-labs/skills/blob/7407f3893ad4dceab546ac002c3ef806e4000c73/README.md
Supports: install
https://github.com/vercel-labs/skills/blob/7407f3893ad4dceab546ac002c3ef806e4000c73/src/git.ts
Supports: install
https://github.com/vercel-labs/skills/blob/7407f3893ad4dceab546ac002c3ef806e4000c73/src/source-parser.ts
Supports: install