Diagnosing Bugs

Diagnosing Bugs#

Disciplined diagnosis loop for hard bugs and performance regressions.

Description#

The diagnosing-bugs skill enforces a six-phase discipline in which building a tight, red-capable feedback loop comes first and hypothesis building is forbidden until that loop exists:

  1. Build a feedback loop — one fast, deterministic, agent-runnable command that goes red on the user’s exact symptom. Ten construction strategies are provided, from failing tests to bisection harnesses.

  2. Reproduce + minimise — watch it go red, then shrink the repro until every remaining element is load-bearing.

  3. Hypothesise — 3–5 ranked, falsifiable hypotheses, shown to the user before testing.

  4. Instrument — probes mapped to predictions, one variable at a time, every debug log tagged (e.g. [DEBUG-a4f2]) for one-grep cleanup. Performance regressions are measured and bisected, not logged.

  5. Fix + regression test — regression test before the fix, but only at a correct seam; a missing seam is itself a finding.

  6. Cleanup + post-mortem — repro re-run, instrumentation removed, the winning hypothesis recorded in the commit message, and a what-would-have-prevented-this recommendation (the complexity skill can quantify architectural hotspots).

Triggers#

/wf:diagnosing-bugs

Also: “diagnose this”, “debug this”, “performance regression”.

Output#

A fixed bug with a regression test (or a documented seam gap), a clean tree, and the confirmed hypothesis in the commit message.

Attribution#

Adapted from the diagnosing-bugs skill in mattpocock/skills (MIT license).

Contents