diagnose
by mattpocockdiagnose is a structured debugging workflow for hard bugs, flaky tests, and performance regressions. It helps you reproduce the issue, minimise the failing case, form one hypothesis at a time, add instrumentation, fix the root cause, and lock it in with a regression test. Use the diagnose guide when “debug this” is not enough.
This skill scores 74/100, which means it is worth listing for users who need a disciplined bug-diagnosis workflow, but it is not yet a highly polished install decision page. The repository gives enough concrete process guidance for agents to use it with less guesswork than a generic prompt, especially around building a deterministic feedback loop and choosing reproduction methods.
- Explicit trigger and scope for hard bugs, throwers/failures, and performance regressions in the frontmatter.
- Strong operational guidance: Reproduce → minimise → hypothesise → instrument → fix → regression-test, with concrete ways to build a pass/fail loop.
- Includes a runnable human-in-the-loop shell template, which improves agent-triggerability for interactive reproduction workflows.
- The visible evidence is skewed toward diagnosis methodology; the excerpt does not show the full end-to-end workflow, so install users may need to fill in some execution details.
- Experimental/test signal and no install command in SKILL.md may make adoption feel less turnkey than more mature skills.
Overview of diagnose skill
What diagnose is for
The diagnose skill is a structured debugging workflow for cases where a bug is hard to pin down, a test is flaky, or performance has regressed and you need a reliable way to isolate the cause. It is best for agents and developers who want more than a generic debug this prompt: they need a repeatable path from symptom to reproduction, then to hypothesis, instrumentation, fix, and regression test.
Who should install it
Install the diagnose skill if you often work on codebases where failures are intermittent, environment-dependent, or only visible in the UI or production-like flows. It is especially useful for Debugging in projects where a quick code skim is not enough and you need a disciplined way to create a pass/fail signal before touching implementation.
What makes it different
The diagnose skill is centered on building a fast feedback loop first. That is the main differentiator: it prioritizes reproducibility and observability over premature code changes. It also encourages using the project’s glossary and ADRs so the agent can align with domain language instead of guessing module intent.
How to Use diagnose skill
Install diagnose skill
Use the skill install path from the repository, then confirm the skill files are available in your local skills directory. For this repo, the documented install command is:
npx skills add mattpocock/skills --skill diagnose
After install, start with SKILL.md, then inspect the supporting files that shape the workflow. The most relevant repository paths are scripts/hitl-loop.template.sh and any project-specific documentation that explains terms, architecture, or testing boundaries.
Turn a vague bug into a good diagnose prompt
The diagnose skill works best when your input includes a concrete symptom, where it happens, and what success looks like. A weak prompt says “diagnose this.” A stronger prompt says:
“Diagnose why the export button sometimes fails in staging. Reproduce it in the browser, minimize the steps, identify whether the issue is server-side or client-side, and add a regression test if possible.”
For diagnose usage, include:
- the observed failure mode
- the environment where it happens
- any known-good or known-bad examples
- whether you can run tests, a dev server, or a browser harness
Suggested workflow and files to read first
Start with SKILL.md to understand the loop, then read scripts/hitl-loop.template.sh if the bug requires human-in-the-loop reproduction. That script is useful when the agent needs the user to click through steps, capture an error, or confirm behavior while the agent parses the result.
A practical workflow is:
- identify the narrowest failing scenario
- build a deterministic signal
- test one hypothesis at a time
- instrument only where the signal is unclear
- lock the fix with a regression test or replayable harness
Tips that materially improve output
If you want better diagnose for Debugging results, tell the agent what tools are allowed: unit tests, CLI commands, HTTP requests, browser automation, or replaying captured traces. Also mention whether the bug is deterministic, flaky, or performance-related, because that changes how the loop should be built. The more specific the observable signal, the less time the agent spends guessing.
diagnose skill FAQ
Is diagnose better than a normal debug prompt?
Usually yes, when the issue is hard to reproduce or spans multiple layers. A normal prompt may jump straight to code changes; diagnose is designed to create evidence first, which is safer for flaky bugs and regressions.
When should I not use diagnose?
Do not use diagnose for straightforward syntax errors, obvious null checks, or tiny one-file fixes where the failure is already fully explained. In those cases, the overhead of a full diagnose guide may be more than you need.
Is the diagnose skill beginner-friendly?
Yes, if you can describe the symptom clearly and run the suggested checks. It is most helpful when you are unsure where the bug lives, because it gives structure to the investigation instead of requiring deep prior knowledge.
Does diagnose fit every stack?
It fits most stacks that can expose a test, script, browser check, or replayable input. It is less useful when the system has no deterministic way to observe success or failure, since the skill depends on a reliable feedback loop.
How to Improve diagnose skill
Give the skill a stronger starting signal
The biggest improvement comes from better reproduction detail. Instead of “the app is broken,” provide the exact action, data shape, and expected versus actual result. If you have logs, a failing URL, a payload sample, or a minimal fixture, include it up front.
Remove ambiguity before asking for root cause
If there are multiple possible failures, name the one you want diagnosed first. For example, separate “the button does nothing” from “the request returns 500” and from “the page is slow.” Diagnose works best when the initial problem statement maps to one observable failure mode.
Use the first pass to choose the next experiment
After the first output, improve diagnose skill results by answering one of three questions: did the reproduction become deterministic, did the hypothesis narrow the search, or do you need a different signal? If the output is still vague, ask for a smaller harness, a different test seam, or a browser/CLI replay path instead of asking for a broad explanation again.