Agent skill · sammcj
diagnose-hard-problem
Disciplined diagnosis loop for hard problems, diagnosing bugs and regressions. Reproduce → minimise → hypothesise → instrument → fix → regression-test.
What it needs
About 6k tokens when loaded.
What this skill does
Diagnose A discipline for hard bugs. Skip phases only when explicitly justified. When exploring the codebase, use the project's domain glossary to get a clear mental model of the relevant modules, and check ADRs in the area you're touching. Note: In addition to this skill, you may consider activating the systematic-debugging skill when diagnosing complex, persistent issues. Redact This skill has you show commands, outputs and captured artifacts. Redact every secret first - write <REDACTED> in its place. Build loops against env vars, so the credential stays in the environment rather than in what you show. Captured artifacts carry auth headers: quote only the lines that carry the signal. If the redacted output is not enough to diagnose the bug, say so and ask the user. Phase 1 - Build a feedback loop This is the skill. Everything else is mechanical. If you have a fast, deterministic, agent-runnable pass/fail signal for the bug, you will find the cause - bisection, hypothesis-testing, and instrumentation all just consume that signal. If you don't have one, no amount of staring at code will save you. Spend disproportionate effort here. Be aggressive. Be creative. Refuse to give up. Ways to construct one - try them in roughly this order 1. Failing test at whatever seam reaches the bug - unit, integration, e2e. 2. Curl / HTTP script against a running dev server. 3. CLI invocation with a fixture input, diffing stdout against a known-good snapshot. 4. Headless browser script (Playwright / Puppeteer) - drives the UI, asserts on DOM/console/network. 5. Replay a captured trace. Save a real network request / payload / event log to disk; replay it through the code path in isolation. 6. Throwaway harness. Spin up a minimal subset of the system (one service, mocked deps) that exercises the bug code path with a single function call. 7. Property / fuzz loop. If the bug is "sometimes wrong output", run 1000 random inputs and look for the failure mode. 8. Bisection harness. …
How to use it
Reference it in AdaL, Claude Code, Cursor or any coding agent — nothing to install:
@skills sammcj/diagnose-hard-problem--c63025