Review Packet: Performance

When to use

Use this packet for new high-traffic routes, slow interactions, landing pages, dashboards, third-party scripts, major dependency additions, rendering changes, and performance regressions.

Intake questions

• Which user-visible metric is at risk?
• Which route, device class, and network class matter most?
• What is the current p75 LCP, INP, CLS, and error rate?
• What new JavaScript, CSS, images, fonts, requests, or third parties are added?
• What work runs on the main thread during the critical interaction?
• What is the rollback or kill-switch path?

Required artifacts

• Route performance budget.
• Request and bundle inventory.
• Browser trace for the critical route or interaction.
• React/component profile if render work is suspected.
• Third-party register.
• RUM segmentation plan.

Decision matrix

Symptom	Likely evidence	Common architecture response
Slow LCP	Waterfall, image/font/render-blocking trace	Improve critical resource priority, rendering model, cache, image strategy.
Poor INP	Interaction trace, long tasks, React profile	Reduce render fan-out, move state, split work, virtualize, remove blocking scripts.
High CLS	Layout shift trace	Reserve dimensions, stabilize font/media loading, avoid late inserts.
Mobile-only slowness	RUM by device/network	Reduce JS, defer noncritical work, improve caching and payloads.

Red flags

• Only lab metrics are used for a production-heavy decision.
• Budgets are global instead of route-specific.
• Third-party scripts have no owner.
• Memoization is proposed before profiling.
• Performance exceptions have no expiration date.

Approval criteria

• Budget impact is known before launch.
• Field metrics and lab checks are both planned.
• Critical interaction has a trace or justified baseline.
• Regression owner and response path are clear.
• Third-party cost is governed.

Example reviewer comments

• "This adds 80 KB to the authenticated shell. Please prove it is needed above the fold or move it behind the route boundary."
• "The INP risk is not bundle size; the profile shows table state invalidates the whole page."
• "This script needs an owner, purpose, loading strategy, and kill switch before approval."

Example ADR prompt

Write an ADR documenting the performance problem, evidence, selected optimization, rejected options, tradeoffs, budget impact, verification plan, and recurrence guardrail.

Release readiness checklist

• Route budget updated.
• p75 field metric baseline captured.
• Critical trace attached.
• Third-party changes reviewed.
• Monitoring alert or dashboard exists.