Hard-Bug Diagnosis Loop
A disciplined debugging loop for hard bugs and performance regressions: reproduce → minimise → hypothesise → instrument → fix → regression-test.
The skill explicitly requires redacting secrets (<REDACTED>) before showing commands/output, and suggests keeping credentials in environment variables, demonstrating data-flow transparency and least privilege. However, it allows adding temporary production instrumentation (Phase 1) without explicitly requiring user confirmation or rollback plan, posing potential risk. Publisher identity is not verified, but source attribution is clearly indicated in README and license (Matt Pocock). Deductions: no explicit user confirmation before production instrumentation, and no clear rollback mechanism.
The skill provides a structured phased debugging process, including feedback loop construction, minimization, hypothesis, instrumentation, fix, and cleanup, logically consistent. However, static review cannot verify actual execution, and the skill relies on user-provided environment and human intervention (e.g., HITL script). Error handling and failure feedback are only briefly mentioned when unable to build a loop, lacking detailed guidance. Deductions: no tests prove key-path viability, failure feedback descriptions are not detailed.
The skill clearly defines applicable scenarios (hard bugs and performance regressions) and trigger conditions (when user says 'diagnose'/'debug'), and provides detailed operational flow. However, it does not explicitly state non-fit scenarios (e.g., simple bugs, non-code environments), and lacks mention of environment fit (e.g., mainland-China network reachability). Deductions: non-fit boundaries vague, no mainland-China environment adaptation notes.
Skill file has clear structure with description, metadata, phases, and checklists; information architecture is sound. License (MIT), versioning (package.json and changesets), and release workflow are present, with maintenance responsibility clearly identified (Matt Pocock). However, missing install/dependency notes (e.g., required environment variables) and incomplete FAQs/known-limitations sections. Deductions: dependency notes and troubleshooting are insufficient.
The skill provides a detailed debugging methodology that could effectively resolve hard bugs. However, static review cannot verify whether actual outputs are directly usable, and output highly depends on user environment and codebase; marginal value is hard to quantify. Deductions: lack of representative output examples, unable to verify actual effectiveness.
Repository includes a CI workflow (release.yml), but it only handles version releases and does not contain tests for skill content. No independent third-party verification evidence; skill core content cannot be independently reproduced via static review. Deductions: no test suite or third-party execution evidence.
- The skill permits adding temporary production instrumentation without explicit user confirmation or rollback plan; exercise caution and obtain consent first.
- The skill is heavily dependent on local environment and codebase; may not work for non-code or remote settings, and does not mention mainland-China network adaptation.
- Static review cannot verify actual effectiveness; recommend trial in real projects and validate the debugging loop's efficacy.
What does this skill do, and when should you use it?
This skill codifies debugging into a six-phase discipline with the core principle of building a tight, red-capable feedback loop before any hypothesis. It guides you through constructing a deterministic, fast repro, minimising it to load-bearing elements, generating falsifiable hypotheses ranked for the user, instrumenting with tagged debug logs, writing a regression test before the fix, and finishing with cleanup and a post-mortem. It emphasizes redaction of secrets in all command output and captured artifacts. It is one of 35 skills in the mattpocock/skills monorepo, MIT-licensed, installable via skills.sh or a Claude Code plugin, and works alongside sibling skills like /tdd and /improve-codebase-architecture.
It provides a step-by-step debugging protocol. Phase 1 prioritizes building a feedback loop (failing test, curl/HTTP script, CLI fixture, headless browser, trace replay, throwaway harness, fuzz loop, git bisect harness, differential loop, or human-in-the-loop script) and requires it to be 'red-capable' (asserts the user's exact symptom), deterministic, fast, and agent-runnable. It instructs reading CONTEXT.md and ADRs, redacting secrets from shown commands/artifacts/auth headers, generating 3-5 ranked falsifiable hypotheses and showing them to the user before testing, instrumenting with uniquely-prefixed logs, measuring a performance baseline first, writing a regression test before the fix at a correct seam, and cleaning up after by removing all [DEBUG-...] tags, deleting throwaway prototypes, and stating the correct hypothesis in the commit message. It also checks off completion criteria and can hand off architecture improvements to the /improve-codebase-architecture skill.
- A developer faces an intermittent crash with no clear repro; the skill guides building a loop that drives the repro rate up from 1% to a debuggable level.
- An engineer observes a performance regression in production; the skill's perf branch tells them to measure a baseline first, then bisect rather than guess.
- A bug only occurs in a complex multi-service environment; the skill suggests replaying a captured trace or building a minimal harness to isolate the code path.
- An agent starts reading code and forming theories prematurely; the skill stops that and demands a red command first.
- A developer must debug while handling sensitive data; the skill's redaction rules ensure no secrets leak into logs or shared output.
- After a fix, the team wants to prevent regression; the skill mandates a regression test at a correct seam or documents the absence of one.
What are this skill's strengths and limitations?
- Forces a feedback loop first, preventing premature hypothesizing.
- Actionable and metric-driven with explicit criteria for 'tight' and 'red-capable'.
- Built-in redaction rules for safe handling of secrets in output.
- Guides generating multiple falsifiable hypotheses and includes a user checkpoint to re-rank them.
- Systematic regression testing and cleanup protocol reduce recurrence.
- Designed for agent autonomy with limited human-in-the-loop via a provided script template.
- Overkill for trivial bugs; it expects you to skip phases only with justification.
- Heavily depends on user-provided access and environment to build loops; can stall if unavailable.
- No test suite or CI validates the skill itself.
- Some references (like the HITL script template) are not included in the repo, requiring user creation.
- Primarily targets code debugging; less useful for infrastructure-only issues.
How do you install this skill?
Install the whole collection via skills.sh: run npx skills@latest add mattpocock/skills and pick the skills you want and which agents to install on, ensuring you select /setup-matt-pocock-skills. Alternatively, install as a Claude Code plugin: in Claude Code run /plugin marketplace add mattpocock/skills and /plugin install mattpocock-skills@mattpocock. Then run /setup-matt-pocock-skills once per repo to configure the environment.
How do you use this skill?
The skill is model-invoked: it triggers when the user says 'diagnose' or 'debug this', or reports something broken/throwing/failing/slow. It can also be manually invoked. Follow the phases in SKILL.md: first read CONTEXT.md and any relevant ADRs; in Phase 1 build a tight feedback loop (if you cannot, say so and ask the user for access/artifacts); then reproduce and minimise, hypothesise (show 3-5 ranked falsifiable hypotheses to the user), instrument with tagged logs, write a regression test before fixing, and finally clean up and post-mortem.