diagnose
Installation
Summary
Structured debugging workflow for reproducing, minimizing, and fixing hard bugs and performance regressions.
- Prioritizes building a fast, deterministic feedback loop (failing test, curl script, CLI fixture, browser automation, or replay harness) before any hypothesis testing—the loop is the core skill
- Requires explicit reproduction confirmation, ranked falsifiable hypotheses, and targeted instrumentation mapped to specific predictions before attempting fixes
- Includes techniques for non-deterministic bugs (raising reproduction rate through loops and stress), performance regressions (baseline measurement and bisection), and cases where no loop is possible (explicit stop with artifact requests)
- Enforces regression test writing at the correct architectural seam before applying fixes, cleanup of debug instrumentation, and post-mortem analysis to identify preventative architectural changes
SKILL.md
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.
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.