Perf Profiling

AI-consumed reference. Optimized for Claude to read during execution. Human-readable explanation: see docs/architecture/HIERARCHICAL_PLANNING.md or docs/getting-started/ depending on topic.

Performance Profiling

Rule 0: Don't optimize what you haven't measured. Almost all "obvious" optimizations are wrong.

The Protocol

Step 1 — Define "fast enough"

Performance is relative. Before optimizing:

• Current metric (p50, p95, p99 latency / MB memory / % CPU)
• Target metric (what's the SLO/SLA/user expectation?)
• Gap — what needs to close

If no target → ask the user. Don't optimize without a goal — you'll polish forever.

Step 2 — Measure baseline

Use the appropriate profiler:

Run the profiler under realistic load, not trivial input. Capture for 30–60s minimum — short captures miss long-tail events.

Step 3 — Analyze (flamegraph / top consumers)

Identify the top 3 functions by:

• Self time (function's own CPU, excluding descendants)
• Total time (self + descendants)
• Call count (high-frequency cold functions add up)

Pareto check: Is there a clear 80/20?

• Top function takes 50%+ of time → that's your target
• Time spread evenly across 100 functions → hard to optimize; likely needs architectural change

Step 4 — Form optimization hypothesis

For the bottleneck:

• What's it doing? (read the code)
• Why is it slow? (algorithm, I/O, allocations, lock contention, cache miss)
• What's a realistic improvement target?

Common bottleneck classes + fixes:

Step 5 — Implement one change, re-measure

One change at a time. Multiple simultaneous changes = unknown which one helped.

Measure the same workload after the change. Compute speedup. If < 10% improvement on the targeted bottleneck: wrong hypothesis — revert, try next.

Step 6 — Verify no regression elsewhere

Optimization can break correctness OR slow other paths. Run:

• Full test suite (correctness)
• Broader benchmark (other metrics didn't degrade — memory, throughput, p99)

Step 7 — Document

In PR or commit message:

• Baseline metric
• Change made
• New metric
• Speedup factor
• Why this change worked (root cause of slowness, not "just faster")

Anti-Patterns

• Micro-optimization without measurement — replacing map with a for loop "for speed" when the bottleneck is elsewhere
• Optimizing cold code — code that runs rarely. Total impact = 0 even if 10× faster per call
• Premature async — async has overhead. Sync code often wins for CPU-bound small tasks
• Cache everything — caches add memory, invalidation bugs, staleness. Cache when measured benefit > cost
• One benchmark run — variance is huge. Run 10+ times, take p50 + std dev
• Microbenchmarking in isolation — function is fast in a benchmark, slow in production due to cache/JIT/load differences

When Architecture Change Is Needed

If profiling shows a flat distribution (no single bottleneck), OR if the target is 10× faster: individual optimizations won't close the gap. Options:

• Algorithm change — different approach entirely (not a tweak)
• Move work to a different tier — client → server, server → precomputed, online → offline
• Different data structure — array → tree, hash → trie, sync → event stream
• Different runtime — interpreted → compiled, single-threaded → parallel, CPU → GPU

These are architectural calls. Use self-consistency for trade-off analysis, tree-of-thoughts for exploring design branches.

Optimization Playbook by Layer

Once profiling (above) has named the bottleneck, apply the fix for its layer. Still one change at a time, re-measure each. Don't apply these blind — they're the fix menu, not a checklist to run through.

Profiler → metric map

Frontend

Core Web Vitals targets: LCP < 2.5s · FID/INP < 100ms · CLS < 0.1.

Quick wins once the profile points here:

• loading="lazy" on below-the-fold images; serve WebP/AVIF.
• Route/component code splitting: lazy(() => import(...)) so first paint ships less JS.
• debounce/throttle high-frequency handlers (scroll, resize, input).
• useMemo/memoization for expensive re-computations; avoid re-render storms.
• Cache headers on static assets; preload critical fonts.

Backend

Database

EXPLAIN ANALYZE the slow query. Seq Scan on a large table = bad; Index Scan = good. Match the index type to the access pattern:

Caching (any layer)

Invalidation strategy: time-based, event-based, or version-based. Remember the anti-pattern above — cache only when measured benefit > memory + invalidation cost.

Memory leaks

Output Format

## Performance Profile: [task / endpoint / function]

**Baseline:** p50=Xms, p95=Yms, p99=Zms, memory=N MB
**Target:** p95 < Wms (source: [SLO / user request])
**Gap:** Yms − Wms = Kms to close

**Bottleneck:** [function/query/operation] — X% of total time
**Root Cause:** [why it's slow]

**Optimization Applied:** [single change]
**After:** p50=X'ms, p95=Y'ms, p99=Z'ms
**Speedup:** [factor]

**Correctness:** [tests pass]
**Broader Impact:** [other metrics checked, no regressions]

Tie-Ins

• skills/self-consistency/SKILL.md — for architectural decisions
• skills/tree-of-thoughts/SKILL.md — explore optimization branches
• rules/core/verification.md — measure before + after, not just after
• commands/check.md — /check perf uses this skill
• rules/core/simplicity-over-complexity.md — the winning optimization is usually "do less," not "do the same thing with a clever structure"