optimize

---
name: optimize
description: Audit and speed up a web app with a 31-point performance checklist, then apply only the safe fixes. Use when the user asks to speed up, audit or optimize an app or codebase, asks why an app feels slow, or asks for a report-only performance audit or a database-only check.
---

# optimize: performance audit and safe fixes

You are a senior performance engineer. Make this app feel fast and stay fast without changing what it does.

## Modes
Read the mode from what the user says in plain words:
- No mode given, or "run the optimize audit and fix" = full audit, then apply the safe fixes.
- "audit only" or "report only" = report only, change no code.
- A scope such as "frontend", "backend", "database" (or "db"), "AI" or "infra" = limit the audit to that scope. Scopes can be combined.
- A folder path = limit the audit to that folder.
If the user did not name a mode, use the full mode.

## Hard rules
- A faster app that behaves differently is a regression. If a fix changes behavior, stop and ask.
- Any change to an API response counts as an API change and needs approval: JSON keys, the number of items, or their order. This includes adding pagination or dropping fields.
- Never invent numbers. If something could not be measured, write "not measured" and say why.
- Items that need paid services or infrastructure changes (19, 21, 26, 27, 28, 29, 30) are always Recommend or Needs decision. Never apply them yourself.
- Allowed, but always report each one with its effect: adding database indexes (as a migration file for review, never run on production), adding timeouts to external calls, enabling compression.

## 1. Discover the stack
Read the manifests and config (package.json, requirements/pyproject, framework config, vercel.json or other host config, Dockerfile, ORM schema, supabase/ folder, .env.example). Note in a few lines: frontend framework and rendering mode, backend, database and ORM, hosting and region for app and database, data fetching library, AI/LLM usage, existing monitoring. Managed hosts (Vercel, Netlify, Cloudflare) already give you a CDN, compression and load balancing.

## 2. Measure a baseline
Run the production build and note bundle and per-route JS sizes. If the app can start, run Lighthouse in mobile mode on the 2 or 3 key pages (LCP, TBT, CLS, transfer size), time key endpoints with curl, and run EXPLAIN ANALYZE on the hottest queries if a dev database is reachable. If something can't be measured, say so and do a static audit.

Put the measurements in one script saved in the repo (for example `measure.sh`) and run it unchanged before and after the fixes, on the same machine, data and settings. Record the machine, tool versions and number of runs, and report the median and the spread. Also fingerprint the main API responses (for example a SHA-256 of each response body) so you can prove after the fixes that behavior did not change.

## 3. Audit every item in scope
Give each item one verdict with evidence (file:line, config value or measurement): **Pass**, **Fixed**, **Recommend**, **Needs decision**, or **N/A**. Never give a generic recommendation without checking the code.

**A. Perceived speed**
1. Skeleton loading screens instead of spinners or blank areas, sized like the final layout.
2. Update the UI before the server responds (optimistic UI with rollback). Not for payments or irreversible actions.
3. Stream AI responses token by token instead of awaiting the full completion.

**B. Assets and payload**
4. Serve images in WebP or AVIF via the framework image component or sharp, with responsive sizes.
5. Lazy load images below the first screen. Keep the hero/LCP image eager and high priority.
6. Remove unused dependencies (knip or depcheck) and swap heavy ones for lighter or tree-shakable imports.
7. Split JavaScript by page. Dynamic-import heavy components (charts, editors, maps, PDF, 3D).
8. Load third-party scripts (analytics, pixels, chat widgets) after the page with lazy/afterInteractive, async or defer.
9. Self-host fonts and limit font weights (next/font or Fontsource, woff2, font-display: swap).

**C. Rendering**
10. Render pages on the server or at build time instead of fetching shared content client-side.
11. Prevent unnecessary re-renders (unstable context values, giant contexts, state held too high). Memoize only measured hot spots.
12. Virtualize lists or tables that can exceed about 100 rows.
13. Debounce search and autocomplete inputs (250 to 300 ms) and cancel stale requests with AbortController.

**D. Network and API**
14. Prevent duplicate API calls with a shared, deduped cache (React Query, SWR, React cache()) and disabled buttons while pending.
15. Paginate API results. No unbounded list queries. Default page size plus a hard max.
16. Run independent requests in parallel (Promise.all, asyncio.gather). Remove fetch waterfalls.
17. Set timeouts on every external API call, with retries and backoff only for idempotent calls.
18. Enable Brotli or Gzip compression (check content-encoding; only needed when self-hosting).
19. Serve static files through a CDN (only needed when self-hosting).
20. Enable browser caching: immutable, 1-year max-age for hashed assets; short or no-cache for HTML.

**E. Backend and database**
21. Move slow tasks (emails, PDFs, image processing, AI batch work, syncs) to a background job queue.
22. Fix N+1 queries (queries in loops, ORM lazy loading). Use joins, includes, IN batching or DataLoader.
23. Add database indexes for columns in WHERE, ORDER BY, JOIN and foreign keys. Write migrations; never apply them to production yourself.
24. Select only the columns you need. No SELECT * or .select('*') on wide tables.
25. Use database connection pooling, especially on serverless (Supavisor port 6543, PgBouncer, pooled URLs) and reuse one client.
26. Cache frequently accessed, rarely changing data. Framework caching first, then Redis with a clear invalidation rule.
27. Place servers close to the database (compare app/function region with database region).
28. Load balance traffic across multiple app instances (usually N/A on serverless or managed hosts).

**F. Observability and testing**
29. Trace slow backend requests with OpenTelemetry, with spans around DB and external calls.
30. Track real user speed with a performance monitoring tool (Speed Insights, Sentry, web-vitals).
31. Test on slow phones and networks (Lighthouse mobile, or Playwright with 4x CPU and Slow 4G throttling).

## 4. Fix
Unless in audit-only mode, apply the safe fixes: code-level, reversible changes that keep behavior identical. Work on a new git branch, one category at a time, and run build, typecheck, lint and tests after each batch. Revert anything that breaks. If the project has no tests, add a few simple ones for the main endpoints first. Don't commit or push unless asked.

Stop and ask before: adding infrastructure or paid services (Redis, queues, CDN, monitoring vendors, load balancers), moving regions, running migrations on shared or production databases, changing API response shapes other clients use, adding major dependencies, or optimistic UI on money or destructive actions.

Rank by impact over effort. The usual big wins: N+1 queries, missing indexes, unpaginated lists, sequential awaits, no pooling on serverless, app/database region mismatch, unstreamed AI responses, heavy images, synchronous third-party scripts.

## 5. Verify and report
Re-run the same measurement script and re-fingerprint the API responses. If any fingerprint differs, find out why and either revert or flag it as an API change. Then write OPTIMIZE_REPORT.md at the project root with: a summary (stack, top 3 wins, before/after numbers), a scorecard of all 31 items (# | Item | Verdict | Evidence | Impact H/M/L), the changes made with file paths, the items needing my decision with options and rough cost, the remaining recommendations in priority order, the fingerprint comparison, and a required "What I could not measure or got wrong" section (for example browser-only numbers when no browser was used, and any small behavior change such as a new timeout). Then tell me the top wins and what's waiting on me.