Diagnosing Bugs

What it does

The central requirement is a fast, red-capable command that exercises the user’s exact symptom. The skill then minimizes the reproduction, ranks falsifiable hypotheses and changes one variable per probe. Its performance branch starts with measurement rather than broad logging. Regression tests must exercise the real bug pattern at an appropriate seam. The cleanup phase removes temporary instrumentation and reruns the original scenario. Diagnostic artifacts require careful secret handling throughout.

When to use it

• A sporadic checkout failure has resisted several speculative fixes.
• A command produces the wrong result for one particular input.
• A recent change increased response latency without a clear cause.

Step-by-step workflow

1. Build and run a repeatable command that fails on the precise reported symptom.
2. Reduce inputs and setup one element at a time while preserving that failure.
3. Write three to five ranked hypotheses with predictions that can be disproved.
4. Test those predictions with focused instrumentation or a timing baseline, changing one variable at a time.
5. Create an appropriate regression case, apply the fix, rerun the original loop and remove debug artifacts.

Example request

Use diagnosing-bugs for the duplicate order created after a payment timeout. First produce one safe local command that catches two orders for one idempotency key. Use synthetic data and test credentials kept outside output. Minimize the failing path, state competing hypotheses and test one prediction at a time. Verify both the minimized case and the original request sequence after the fix. Do not instrument production or expose request headers.

Worked example

A test that only asserts a request returns successfully cannot catch duplicate orders. A stronger reproduction simulates a timeout and retry, then checks that exactly one order exists for the key. Removing unrelated shipping data can reveal which timing and retry conditions matter. A hypothesis about the uniqueness check must predict an observable difference. After correcting the responsible behavior, rerunning the full sequence matters because a narrow helper test could miss the interaction that originally failed.

What you get

A reproducible failure command, evidence for the cause, a targeted fix and a regression check where a suitable seam exists.

How to evaluate the result

• Observe the exact symptom fail before accepting the reproduction.
• Verify the fix passes the original scenario as well as the reduced case.
• Remove temporary logs and confirm no credentials entered diagnostics or commits.

What you need

Access to a safe reproducing environment, representative synthetic inputs and tools capable of running the failure loop. Performance work needs comparable measurements.

Setup and activation

The publisher documents plugin setup for Claude Code, Codex and Copilot, and manual Agent Skills setup for Gemini CLI and other clients. Choose one distribution method per client to avoid duplicate skills. The engineering collection expects project-specific tracker, triage-label and document-location settings from setup-matt-pocock-skills. Keep referenced companion skills and files available. This catalogue review does not install or run them; scan the exact source before any later installation. Client tools, permissions and subagent support still need separate validation.

Limits and considerations

A missing reproducible signal is a blocker to confident diagnosis, not permission to guess. Timing bugs may need a controlled high reproduction rate. Production instrumentation requires separate authorization. Captured traces can contain secrets and must never be published unreviewed.

Related workflows

• Use codebase-design when no seam can reproduce the interaction safely.
• Use code-review to assess the final fix against requirements and project standards.

License and reuse

MIT at repository level (Copyright 2026 Matt Pocock). Preserve the copyright and permission notice when redistributing substantial source material; inspect any separately licensed dependencies or assets.

Further reading

• Publisher README: client setup and companion skills
• Reviewed SKILL.md (immutable commit)
• Reviewed MIT license