diagnosing-bugs

Topics in the source

• Diagnosing Bugs
• Redact
• Phase 1: Build a feedback loop
• Ways to construct one, in roughly this order
• Tighten the loop
• Non-deterministic bugs
• When you genuinely cannot build a loop
• Completion criterion: a tight loop that goes red

A discipline for hard bugs. Skip phases only when explicitly justified. 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. This skill has you show commands, outputs and captured artifacts. Redact every secret first: write 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. 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. Spend disproportionate effort here. Be aggressive. Be creative. Refuse to give up. 1. Failing test at whatever seam reaches the bug: unit, integration, e2e. 2. Curl / HTTP script against a running dev server. 3. CLI invocation with a fixture input, diffing stdout against a known-good snapsho

This is an excerpt. Refer to the complete source and its current requirements.