name: debugging
description: How to investigate a hard bug without tunnel-visioning on one method. Triggers: a hypothesis just failed, a second same-category fix attempt is about to be proposed, "I'm stuck", a long-running investigation.
Debugging Without Tunnel Vision
Trying new hypotheses but testing all of them with the same method is still tunnel vision, even
though each attempt feels like progress. Cap it: 2 attempts per category below, then switch
categories. (Seen in #3475 — three synthetic unit-test probes for a bug only visible in a real
window.)
Categories
- Static/automated — unit tests, rendering-PNG tests, simplified scenarios
- Live observation — run + logs, breakpoints, user visually confirms
- Historical/comparative — bisect PRs/functionality,
git log/blame, cross-backend diff
- Structural isolation — minimal repro outside the app/framework
- External verification — read the actual upstream source, its issue tracker
- Specialized tooling — GPU frame capture, other domain debuggers
Self-invoke on the 2nd same-category miss — don't wait for the user to point this out (happened
on #3660: 4 rounds of GL/Skia-semantics patches before switching to live-observation logging).
Stop immediately if
- A sanity-check of your own method fails — the method is invalid, not "try harder within it."
- The symptom only shows in a context your current tool can't observe (e.g. a headless test can't
see a real window) — switch categories, don't refine the probe.
Communicate
Narrate switches ("ruled out X, trying Y") instead of going silent. Keep working if confident;
only stop to discuss when genuinely unsure which category to try next.
