Optimize

Optimization Playbook

Authored by Claude Fable 5. The first rule of optimization is that your intuition about what's slow is usually wrong, and the second is that an optimization you didn't measure is just a refactor you're hoping helped.

Why this exists

Unguided optimization is a graveyard of wasted effort: models rewrite a loop that runs once at startup, add memoization that costs more than it saves, and declare victory without a single before/after number. This playbook forces the only workflow that actually produces speedups — measure, find the real hot spot, fix that one thing, measure again to prove it — and forbids speculative micro-tuning.

Phase 0 — Define "slow" as a number

Before touching anything, pin down:

• What's slow, specifically? Initial load? A particular interaction? A query? Scrolling? Get the user to point at the exact experience.
• The target. "Fast" is not a goal. "Interaction responds in <100ms", "bundle under 250KB", "list scrolls at 60fps" are goals. If the user has no number, propose a reasonable one and note it.
• The budget for effort. A 3-second win that takes 2 days may not be worth it; a 300ms win in one line always is.

Gate: you have a specific slow scenario and a target number. Optimizing without these means you can't tell when to stop.

Phase 1 — Measure and locate the bottleneck

Get real numbers before forming any theory:

• Load/bundle: build and read the actual bundle output; identify the largest chunks and dependencies. Use the build's own analysis (bundle size output, source-map explorer) — don't eyeball imports.
• Runtime: profile the slow interaction (browser Performance panel, React DevTools Profiler, console.time, or the platform's profiler). Find where the time actually goes.
• Queries/data: log query counts and timings. The classic killer is N+1 (one query per item in a list) and over-fetching, not slow individual queries.
• Re-renders (React/UI): count them. Excess renders from unstable props or context churn are the most common UI perf bug — and the most commonly misdiagnosed.

Rank what you find. The bottleneck is almost never where it feels like it is. A component that renders 400 times matters more than one slow function that runs once. Amdahl's law is the whole game: a 10× speedup on 5% of the time is invisible; a 2× speedup on 80% of the time is transformative. Spend your effort where the time actually is.

Gate: you can name the single biggest contributor to the slow scenario, with a measured number attached. If you can't, keep profiling — do not start fixing.

Phase 2 — Fix the top bottleneck (only)

Fix the number-one item. Prefer, in order:

1. Do less work — avoid the computation entirely (cache, memoize the expensive thing, lazy-load, paginate, debounce, virtualize a long list).
2. Do it at a better time — defer off the critical path, precompute, move work off the main thread or to build time.
3. Do it faster — algorithmic fix (the O(n²) that should be O(n)), better data structure, fewer round-trips.
4. Ship less — code-split, tree-shake, drop or replace a heavy dependency.

Change one thing at a time. If you batch five optimizations you won't know which helped, and some may have hurt. Keep readability: a clever optimization that nobody can maintain is a liability unless the win is large and measured.

Phase 3 — Prove the win

Re-measure the exact same scenario the same way. Report before/after side by side. If the improvement is negligible, revert it — an optimization that didn't measurably help is just added complexity and risk. Then either move to the next bottleneck (back to Phase 2) or stop if the target is met.

Phase 4 — Report

# Optimization Report — <scenario> — <date>

## Target
<the number we were aiming for>

## Before → After
| Metric | Before | After | Δ |
| <e.g. bundle> | 480KB | 240KB | −50% |

## What changed and why
- <fix> at `file:line` — <the measured bottleneck it addressed>

## Reverted (didn't help enough to justify)
<honesty here keeps the codebase clean>

## Remaining bottlenecks (diminishing returns / out of scope)

Never claim a speedup you didn't measure. "Should be faster" is not a result.