Optimize

Optimize the performance of the file, function, page, or route named in $ARGUMENTS by finding the single real bottleneck, fixing it, and proving the win with before/after numbers that survive measurement noise.

If $ARGUMENTS is empty, ask which target to optimize or which symptom to chase (e.g. "checkout page feels slow") — do not guess the slowest path; let the baseline in step 2 identify it. Confirm before proceeding. Never scatter micro-optimizations across code you have not measured.

Method (in strict order)

1. Define "slow." State the one primary metric that matters for this target: initial load, interaction latency (INP), throughput, query time, memory, or build time.
2. Get a baseline. Measure before touching anything, with the project's real tooling, against a production/release build (minified, optimized, dev-mode and StrictMode double-render off) — dev-mode numbers lie. Run the scenario several times, discard the first (cold/JIT) run, and report the median; for latency metrics (INP, query time, request time) also report p75/p95 and the run-to-run spread. If you genuinely cannot measure now, name the exact command/tool and value to capture, then estimate from code inspection — label it an estimate.
3. Localize the bottleneck to one of the categories below. Rank suspects by expected cost, then confirm the top one with a profile, a log, a query plan, or a bundle report — never fix on a hunch.
4. Fix only the top bottleneck. Smallest behavior-preserving change that removes it. Keep outputs and edge cases identical.
5. Re-measure identically — same build, same trial count, same warm-up — and report median before → after with the spread. Keep the fix if the improvement clearly exceeds run-to-run noise and the profile confirmed this was the top bottleneck; a real 5-8% win on the right target counts and stays. Revert and re-diagnose only if the delta is within noise, or you changed something the profile never implicated.

Where to look, and how to measure each

• Bundle size / load: inspect the production build output (next build, Vite/webpack analyzer, source-map-explorer) and the DevTools Coverage tab. Fixes: dynamic import() and route-level code-splitting, drop or swap heavy deps (e.g. moment→date-fns), tree-shake barrel imports, defer non-critical JS.
• Render / re-render: React DevTools Profiler on a production profiling build (or discount StrictMode's double render and dev overhead) — count renders and flame durations. Fixes: memoize only where the profiler shows wasted renders, stabilize props (no inline objects/arrays/lambdas as deps), stable list keys, virtualize long lists (react-window). Do not sprinkle useMemo/memo blindly.
• Queries (N+1 / slow): log emitted SQL and count queries per request; run EXPLAIN ANALYZE on the slow one across several runs so a warm cache doesn't flatter it. Fixes: add the missing index, batch/join or use a DataLoader, SELECT only needed columns, hoist queries out of loops.
• Network waterfalls: DevTools Network/Performance panel — look for sequential dependent requests. Fixes: parallelize independent calls (Promise.all), remove await-in-loop, prefetch/preload, cache, move fetching server-side.
• Main-thread long tasks: Performance panel — tasks >50ms. Fixes: break up or defer work, debounce/throttle handlers, move CPU work to a Web Worker, avoid layout thrash (batch DOM reads/writes).

Output

• The metric chosen and the baseline: median over N trials plus spread (or p75/p95 for latency), or a clearly-labeled estimate.
• The bottleneck, with the evidence that identified it (profile line, query count, bundle entry).
• The change made and why it targets that bottleneck.
• Median before → after with trial count and spread, and the exact command to reproduce them. If unmeasured, list precisely what to run and what number to record.

Rules

• Measure production builds, never dev: unminified bundles, dev-only warnings, and StrictMode double-renders inflate the numbers you are trying to trust.
• A delta smaller than the run-to-run spread is noise, not a win — never report it as one.
• Detect and follow the project's existing stack, conventions, and tooling — do not introduce a new profiler, library, or pattern without justification.
• Never trade correctness for speed: outputs and edge cases stay identical; keep or add a test that pins current behavior.
• One bottleneck per pass. If a second one remains, report it — don't fix it silently.
• No new dependency unless it removes more weight than it adds; prove it.
• Never claim a speedup you did not measure or cannot reproduce.