Performance Optimization
The Iron Law
HARD GATE - Baseline Requirement:
→ Performance optimization task started → Do I have a recorded baseline metric (number + tool + conditions)?
No → STOP.
Has code already been changed?
Yes → Git stash changes, measure old code, re-apply, measure again.
No → Measure baseline NOW before any changes.
Yes → Proceed to profiling.
No optimization without baseline measurement. No exceptions. Violating the letter of this process IS violating the spirit.
MANDATORY FIRST STEP
TodoWrite: Create items for each phase below.
Never skip measurement:
- 70% of "obvious" bottlenecks are wrong — Profile first
- 40% of optimizations without baseline cause regressions
- Production monitoring dashboards are NOT a substitute for a controlled baseline
Process: BASELINE → PROFILE → STRATEGY → IMPLEMENT → VALIDATE
1. Baseline Measurement (BEFORE any code changes)
Record tool + metric + value + conditions (e.g., "k6 load test: p95 = 4.2s at 100 req/s, dataset: 10k rows"). Must be reproducible — curl wall-clock time is NOT a baseline. Use load testing tools (k6, wrk, vegeta) for APIs, EXPLAIN ANALYZE/pg_stat_statements for databases, APM traces for applications.
2. Bottleneck Analysis (PROFILE, don't guess)
- Profile with appropriate tool (see above)
- Identify slowest operation with specific timing and % of total
- e.g., "orders query = 3.1s, 78% of total request time"
- Determine root cause (N+1 queries, missing index, blocking I/O, serialization)
→ Profiling complete → Does result match initial assumption?
No → Am I tempted to trust my assumption over the data? → STOP. Trust the profiler. Implement based on profiling data, not assumption.
Yes → Implement based on profiling.
3. Optimize and Validate
- Evaluate 2-3 approaches with tradeoffs. State expected improvement.
- Implement minimal change — fix the measured bottleneck only
- Re-measure with same tool, same conditions as step 1
- Compare before/after with specific numbers. Check no regressions.
- Record results in PR description with tool, conditions, and numbers
Red Flags — STOP If You Think Any of These
| Thought |
Reality |
| "Bottleneck is obvious, skip profiling" |
70% wrong without data. Profile first. |
| "We'll measure after" |
Can't validate without before. Measure NOW. |
| "Manual testing / curl is enough" |
Need reproducible metrics, not feelings. |
| "Production dashboards = baseline" |
Different conditions, not controlled. Measure directly. |
| "Senior dev says cache everything" |
That's a hypothesis, not a diagnosis. Profile first. |
| "Already changed the code, too late" |
Roll back, measure old code, re-apply, measure again. |
| "No time to profile" |
15 min profiling saves hours of wrong-direction work. |
| "I've seen this pattern before" |
This system is different. Measure THIS system. |
What To Do When You Skipped Baseline
If you already made changes without measuring:
- Do NOT rationalize retroactive baselines (production dashboards, "estimates")
- Git stash or branch your changes
- Measure the old code with proper tooling under controlled conditions
- Re-apply your changes
- Measure again with identical tool + conditions
- Now you have a valid before/after comparison
This costs 30-60 minutes. Shipping unvalidated "performance improvements" costs trust, debugging time, and potential regressions.
1---2name: performance-optimization3description: Use when optimizing backend, API, database, or system performance. Also use when response times are slow, queries need tuning, throughput is degraded, or someone says "just add caching." Triggers on: optimize API, backend slow, API latency, database performance, query optimization, server response time, connection pooling, N+1 queries, cache strategy, load testing. For frontend/UI performance (Core Web Vitals, Lighthouse accessibility), use frontend-production-quality instead.4---56# Performance Optimization78## The Iron Law910HARD GATE - Baseline Requirement:11→ Performance optimization task started → Do I have a recorded baseline metric (number + tool + conditions)?12 No → STOP.13 Has code already been changed?14 Yes → Git stash changes, measure old code, re-apply, measure again.15 No → Measure baseline NOW before any changes.16 Yes → Proceed to profiling.1718No optimization without baseline measurement. No exceptions. Violating the letter of this process IS violating the spirit.1920---2122## MANDATORY FIRST STEP2324**TodoWrite:** Create items for each phase below.2526**Never skip measurement:**27- 70% of "obvious" bottlenecks are wrong — Profile first28- 40% of optimizations without baseline cause regressions29- Production monitoring dashboards are NOT a substitute for a controlled baseline3031---3233## Process: BASELINE → PROFILE → STRATEGY → IMPLEMENT → VALIDATE3435### 1. Baseline Measurement (BEFORE any code changes)3637Record **tool + metric + value + conditions** (e.g., "k6 load test: p95 = 4.2s at 100 req/s, dataset: 10k rows"). Must be reproducible — `curl` wall-clock time is NOT a baseline. Use load testing tools (k6, wrk, vegeta) for APIs, `EXPLAIN ANALYZE`/`pg_stat_statements` for databases, APM traces for applications.3839### 2. Bottleneck Analysis (PROFILE, don't guess)4041- Profile with appropriate tool (see above)42- Identify slowest operation with **specific timing and % of total**43 - e.g., "orders query = 3.1s, 78% of total request time"44- Determine root cause (N+1 queries, missing index, blocking I/O, serialization)4546→ Profiling complete → Does result match initial assumption?47 No → Am I tempted to trust my assumption over the data? → STOP. Trust the profiler. Implement based on profiling data, not assumption.48 Yes → Implement based on profiling.4950### 3. Optimize and Validate5152- Evaluate 2-3 approaches with tradeoffs. State expected improvement.53- Implement minimal change — fix the measured bottleneck only54- **Re-measure with same tool, same conditions** as step 155- Compare before/after with specific numbers. Check no regressions.56- Record results in PR description with tool, conditions, and numbers5758---5960## Red Flags — STOP If You Think Any of These6162| Thought | Reality |63|---------|---------|64| "Bottleneck is obvious, skip profiling" | 70% wrong without data. Profile first. |65| "We'll measure after" | Can't validate without before. Measure NOW. |66| "Manual testing / curl is enough" | Need reproducible metrics, not feelings. |67| "Production dashboards = baseline" | Different conditions, not controlled. Measure directly. |68| "Senior dev says cache everything" | That's a hypothesis, not a diagnosis. Profile first. |69| "Already changed the code, too late" | Roll back, measure old code, re-apply, measure again. |70| "No time to profile" | 15 min profiling saves hours of wrong-direction work. |71| "I've seen this pattern before" | This system is different. Measure THIS system. |7273---7475## What To Do When You Skipped Baseline7677If you already made changes without measuring:78791. **Do NOT rationalize retroactive baselines** (production dashboards, "estimates")802. **Git stash or branch** your changes813. **Measure the old code** with proper tooling under controlled conditions824. **Re-apply your changes**835. **Measure again** with identical tool + conditions846. **Now** you have a valid before/after comparison8586This costs 30-60 minutes. Shipping unvalidated "performance improvements" costs trust, debugging time, and potential regressions.
pvillega