Frontend debugging: evidence over vibes

The loop

Reproduce → isolate → hypothesis → experiment → verify. One variable at a time; write down what you ruled out. If you can't reproduce it, you're not debugging — you're gambling.

1. Reproduce reliably: exact URL/state/steps, same viewport, throttled CPU/network if intermittent. Save it as a test when possible.
2. Isolate the layer: is it data (network), logic (JS), paint (CSS), or integration (build/env)? DevTools first — console, Network, Elements, Performance — before touching code.
3. Bisect: git history (git bisect) for regressions; component tree (comment out halves) for render bugs; feature flags for config.

Network first (it usually is)

• Filter to the failing request; check status, payload, and timing. A 200 with wrong body is a data bug, not an HTTP bug.
• Reproduce the request in isolation (curl/HTTP file) — separates backend from frontend.
• Watch for the classics: CORS preflight failing, cookie not sent (SameSite), stale SW cache, duplicated requests from double effects.

Render/UI bugs

• Element pick → Computed styles: which rule won, and why (specificity/layers). @layer order and inherited vs set properties explain 80% of "my CSS doesn't apply".
• Z-index: it's not a number war, it's stacking contexts — find the ancestor creating a context (transform/filter/opacity/will-change) before touching z-values.
• Layout shift: Performance panel → Experience track highlights the shifting element.
• "Works in dev, broken in prod": check minified behavior differences, env config, CDN caching of stale HTML/assets.

Reactivity bugs (the big three)

1. Stale closure: a callback captured old state/props. Evidence: value is right in render, wrong in handler. Fix: include the dep, or latest-value ref.
2. Double effects in dev StrictMode: don't "fix" by removing StrictMode; make the effect idempotent (proper cleanup) — prod runs once, dev twice by design.
3. Hydration mismatch (Next/SSR): server and client rendered different trees. Usual causes: Date.now()/Math.random()/locale-dependent formatting during render, browser-only APIs. Fix: compute in effects, or suppressHydrationWarning only where truly cosmetic.

Leaks & jank

• Memory: Allocation instrumentation on the suspect flow; look for detached DOM held by closures, listeners never removed, timers without cleanup.
• Jank: Performance recording → long tasks → what's blocking (layout thrash from read/write interleaving? giant sync DOM update?).

Verification

The bug is fixed when the failing behavior is covered by a regression test or a checklist entry, not when it "looks right on my machine". Write the test while the repro is fresh.

Definition of done (agent checklist)

• Root cause identified with DevTools evidence, not pattern-matching
• One-variable-at-a-time changes; ruled-out causes noted
• Regression test or documented checklist added
• Similar code paths audited for the same bug class