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.