Performance Optimization

Measure before optimizing. Profile first, fix the proven bottleneck, measure again, then guard against regression.

Hard Rules

• Never optimize without a baseline measurement (synthetic + real-user when possible).
• Fix the actual bottleneck — not the most interesting code.
• One change at a time when validating; otherwise you cannot attribute wins.
• Set budgets (LCP, bundle KB, p95 latency) and fail CI when exceeded.
• Document what you measured, what you changed, and the delta.

Core Web Vitals Targets

Workflow

Step 1 — Measure baseline

• Frontend: Lighthouse (synthetic), DevTools Performance, web-vitals RUM.
• Backend: APM, query logs with timing, p50/p95/p99 on critical endpoints.
• Record environment, device, and data volume.

Step 2 — Identify bottleneck

Use symptom → probe map:

Slow first load → bundle size, render-blocking, LCP element
Slow interaction → INP, main-thread long tasks, layout thrash
Slow API → N+1 queries, missing indexes, cold starts
Memory growth → leaks, unbounded caches, retained DOM

Step 3 — Fix narrowly

Prefer highest-impact, lowest-risk fixes: indexes, caching, code-split, image sizing, defer non-critical JS.

Step 4 — Verify

Re-run the same measurement as Step 1. Report before/after numbers.

Step 5 — Guard

Add Lighthouse CI budget, bundle-size check, or perf test on the hot path.

When NOT to use

• No evidence of a problem and no stated budget
• Micro-optimizing cold paths while hot paths are unmeasured
• Replacing architecture before profiling

Gotchas

• Synthetic scores ≠ real-user experience — use both.
• Optimizing the wrong layer (CSS when the DB is the bottleneck).
• Caching without invalidation creates subtle bugs.
• Bundle "tree-shaking" claims without measuring shipped bytes.

Common Rationalizations

Output Format

## Performance report — [area]

Baseline: [metrics + how measured]
Bottleneck: [evidence]
Change: [what]
After: [metrics]
Guard: [CI/monitoring added]

Examples

Verification

• Baseline captured with method and environment noted
• Bottleneck identified with evidence (not assumption)
• After metrics show improvement on the same probe
• Regression guard added or explicitly deferred with reason
• No premature micro-opts on unmeasured paths

Red Flags

• Optimization started without baseline measurement
• CSS or frontend tuned while DB is actual bottleneck
• Multiple changes shipped — win cannot be attributed
• Synthetic score improved but real-user metrics flat

Prune Log

Last pruned: 2026-07-04

• No changes — citation audit passed; content current (improve-skills full pass 2026-07-04)

Impact Report

Area: [frontend/backend] | Baseline: [key metric]
Bottleneck: [one line] | Delta: [before → after]
Guard: [added/deferred]