Diagnose

Source: adapted from mattpocock/skills — engineering/diagnosing-bugs. Synced 2026-09-03 to bring Phase 1 feedback loop criteria and Phase 2 reproduction & minimisation in line with upstream. The ## Redact section below was missing from the original import and is cited separately.

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.

Redact

Source: mattpocock/skills — engineering/diagnosing-bugs, added here 2026-08-26 (missing from this skill's original import).

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.