diagnosing-bugs
Diagnosing Bugs
A discipline for hard bugs. Adapt the phases to the evidence already available; explain any material verification gap.
When exploring the codebase, read GLOSSARY.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.
Phase 1: Build a feedback loop
This is the skill. Everything else is mechanical. A pass/fail signal specific to the bug makes bisection, hypothesis testing and instrumentation more useful. Source inspection and provisional hypotheses can help construct that signal.
Invest in a useful feedback loop in proportion to the difficulty and available access.