Forked from vendor/mattpocock/skills/engineering/diagnosing-bugs at upstream c55ee46 (upstream sync 2026-09-20). Identical to /skill:diagnosing-bugs except the integration points marked [vault] or [methods] below: three ~/ops points plus a /skill:domain-modeling handoff at Phase 6, and debug-methods (facts/hypotheses two-layer discipline, references/debug-methods.md) integration. Keep the fork's drift to those marks only; anything else belongs upstream.

Diagnosing Bugs

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.

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.

[vault] Phase 0: Consult the vault

Before building a feedback loop, run /skill:diag-search with the bug's component, failure type, and symptom keywords. A prior diagnosis may hand you the repro command (Phase 1, half-done) or the root cause outright: an already-diagnosed bug needs no loop at all.

[vault][methods] Phase 0b: Anchor the object