diagnosing-bugs
Diagnosing Bugs
Diagnose hard bugs by combining reproduction, code inspection, provisional hypotheses, and targeted probes. Choose the next step by the evidence missing; the sections below are tools for the investigation, not gates that must be completed in order.
When exploring the codebase, read the project's glossary if it exists, whatever its filename, 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, scrub secrets from any trace before saving it to disk, and keep saved traces outside the repository.
If the redacted output is not enough to diagnose the bug, say so and ask the user.
Build a feedback loop
Start from the user's exact symptom, expected behavior, entry point, environment, inputs, and action sequence. Trace the relevant code and use provisional hypotheses to identify the conditions a reproduction must preserve. Keep those hypotheses distinct from established causes.
Prefer an existing check that can fail on the reported bug and pass after the fix. Build or adapt a feedback loop when it will distinguish causes or verify the outcome; do not require a runnable reproduction before inspecting code or forming a testable explanation.