Diagnosing Bugs

When to Use

Use when this workflow matches the user request: Use this skill for its documented workflow.

Source: mattpocock/skills (MIT).

A discipline for hard bugs. Skip phases only when explicitly justified.

When exploring the codebase, read CONTEXT.md (if it exists) to get a clear mental model of the relevant modules, and check ADRs in the area you're touching.

Use isolated fixtures and approved environments; captured HAR/log/core data and the HITL template can reveal tokens or personal records, so redact before printing or sharing. The bundled template expects an interactive terminal, not an unattended tool pipe. Do not increase stress, repeat writes or instrument production beyond the authorized scope. Static inspection may be needed to locate a safe repro seam; if runtime access is unavailable, report hypotheses as unverified rather than treating this workflow as permission to block all useful analysis.

Phase 1 — Build a feedback loop

This is the skill. Everything else is mechanical. If you have a tight pass/fail signal for the bug — one that goes red on this bug — you will find the cause; bisection, hypothesis-testing, and instrumentation all just consume it. If you don't have one, no amount of staring at code will save you.