debugging

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.