| name | performance-optimization |
| description | Diagnose and improve performance with measurements and source-of-truth constraints. Use when the user reports slowness, latency, high CPU, high memory, slow queries, N+1 issues, large payloads, slow builds, slow tests, rendering lag, bundle size, Core Web Vitals, caching, pagination, image/font loading, queues, background jobs, or asks to profile, optimize, speed up, or reduce resource usage. |
Performance Optimization
Use this skill when performance is the main concern. Measure first, optimize the confirmed bottleneck, and verify improvement without changing business behavior accidentally.
Operating Rules
- Do not optimize blindly. Capture a baseline or concrete symptom first.
- Read project docs, architecture notes, caching rules, database rules, design-system rules, and existing performance conventions.
- Preserve business logic and data correctness.
- Prefer low-risk local improvements before broad architecture changes.
- Treat caching as a contract: define invalidation, freshness, and user-specific data boundaries.
- Avoid adding dependencies or infrastructure unless measurement justifies them.
- If the issue is actually a bug or regression with unclear cause, switch to
debugging-workflow.
- If the issue requires benchmarks, regression tests, or browser visual checks, coordinate with
testing-verification.
Workflow
1. Define The Performance Claim
- Identify what is slow, where, for whom, and compared to what.
- Capture baseline evidence: timing, query count, payload size, memory, CPU, bundle size, Web Vitals, screenshot, profile, or logs.
- Identify the environment and data size used for measurement.
2. Find The Bottleneck
- Separate backend latency, database time, network payload, frontend rendering, asset loading, build tooling, and external dependency time.
- Check source-of-truth docs for expected behavior before changing data flow.
- Inspect existing instrumentation, logs, traces, query debug output, profiler data, and browser performance tools when available.
Read references/performance-playbook.md for domain-specific checks.
3. Choose The Smallest Useful Fix
- Database: indexes, eager loading, joins, batching, pagination, field selection, avoiding N+1.
- Backend: reduce redundant work, stream or queue heavy work, avoid large in-memory operations, cache carefully.
- Frontend: reduce unnecessary renders, split data, virtualize large lists, lazy load, memoize where useful, optimize images/fonts.
- Build/tests: cache dependencies, reduce repeated setup, isolate slow suites, avoid unnecessary full rebuilds.
4. Verify Improvement
- Rerun the same measurement.
- Compare before/after using the same data and environment when possible.
- Add regression coverage or guardrails when practical.
- If performance improved by trading off freshness, correctness, accessibility, or UX, document and confirm that tradeoff.
Reporting
Report:
- Baseline and after measurement.
- Bottleneck identified.
- Change made.
- Verification command, profiler, screenshot, or metric.
- Tradeoffs, cache invalidation rules, and remaining risks.
References
references/performance-playbook.md: database, backend, frontend, asset, build, test, and caching performance checks.
