Diagnosing Bugs

A discipline for the hard ones. Skip a phase only when you can explicitly justify it.

While you're getting your bearings, read CONTEXT.md (if it exists) to build a clean mental model of the modules in play, and check any ADRs covering the area you're touching.

Phase 1 — Build a feedback loop

This is the skill. Everything downstream is mechanical. Give yourself a tight pass/fail signal — one that goes red on this specific bug — and you will find the cause; bisection, hypothesis-testing, and instrumentation are just ways of spending that signal. Without one, no amount of staring at code will rescue you.

Pour disproportionate effort in here. Be aggressive. Be creative. Refuse to give up.

Ways to construct one — try them in roughly this order