Skip to main content

Production Debugging Drills

Why this chapter matters​

Architects need operational imagination. They should be able to predict how frontend systems fail under real users, not only how code behaves in local development.

Debugging drills build that instinct.

Drill format​

For each drill, write:

  • user symptom
  • first five signals to inspect
  • likely causes
  • immediate mitigation
  • long-term guardrail
  • owner

Drill 1: Dashboard is slow only for mobile users​

Symptom​

Mobile users report that the dashboard appears quickly but feels frozen when filtering a table.

Signals to inspect​

  • p75 INP by route, device, and network
  • browser performance trace for filter interaction
  • React profile for state fan-out
  • table row count and virtualization behavior
  • third-party long tasks around interaction time

Likely causes​

  • filter state placed too high in the tree
  • full table rerenders on every keypress
  • expensive derived data runs on main thread
  • analytics handler blocks interaction
  • virtualization missing or misconfigured

Mitigation​

Debounce noncritical analytics, isolate filter state, reduce render fan-out, and cap visible rows. If needed, disable heavy table features behind a flag.

Guardrail​

Add route-specific INP budget, profile fixture for table filtering, and review rule for large interactive lists.

Drill 2: Login works locally but fails after deploy​

Signals to inspect​

  • auth callback status codes
  • cookie attributes and domain
  • redirect chain
  • CSP/connect-src violations
  • CDN cache headers for auth routes

Likely causes​

  • auth callback accidentally cached
  • cookie SameSite/Secure mismatch
  • redirect URL mismatch
  • environment-specific origin not allowed
  • edge rewrite changed callback path

Guardrail​

Auth routes should have explicit no-store policy, callback smoke tests, and deployment checks for origin/cookie configuration.

Drill 3: Conversion drops after analytics launch​

Signals to inspect​

  • Web Vitals by release and campaign
  • third-party request count and blocking time
  • form abandonment step
  • consent and tag loading rules
  • experiment assignment changes

Likely causes​

  • analytics loaded on critical path
  • tag manager injected layout-shifting content
  • script error blocked form handler
  • attribution experiment changed cache behavior

Guardrail​

Third-party register, script budgets, kill switches, and launch review for all acquisition scripts.

Drill 4: AI copilot shows plausible but wrong policy answer​

Signals to inspect​

  • retrieved sources and timestamps
  • citation visibility
  • prompt and model version
  • eval fixture coverage
  • user correction event

Likely causes​

  • stale source retrieved
  • no freshness filter
  • context packed irrelevant chunks
  • model answered without required citation
  • eval suite lacks policy contradiction cases

Guardrail​

Require citation policy, stale-source state, retrieval evals, and production correction review.

Drill 5: A shared component breaks keyboard navigation​

Signals to inspect​

  • component version and changelog
  • focus movement before/after
  • keyboard test coverage
  • consumer overrides
  • accessibility issue reports

Likely causes​

  • prop allowed consumer to remove accessible name
  • focus return behavior changed
  • ARIA role updated without keyboard model
  • visual regression tests passed but interaction tests were missing

Guardrail​

Component accessibility contracts, keyboard fixtures, manual checks for high-risk primitives, and breaking-change policy.

Exercise​

Run one drill against a real feature in your codebase. Do not stop at root cause. Write the guardrail that would have prevented the incident class.