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: >4 Use when optimizing backend, API, database, or system performance. Also use when5 response times are slow, queries need tuning, throughput is degraded, or someone says6 "just add caching." Triggers on: optimize API, backend slow, API latency, database7 performance, query optimization, server response time, connection pooling, N+1 queries,8 cache strategy, load testing. For frontend/UI performance (Core Web Vitals, Lighthouse9 accessibility), use frontend-production-quality instead.10---1112# Performance Optimization1314## The Iron Law1516HARD GATE - Baseline Requirement:17→ Performance optimization task started → Do I have a recorded baseline metric (number + tool + conditions)?18 No → STOP.19 Has code already been changed?20 Yes → Git stash changes, measure old code, re-apply, measure again.21 No → Measure baseline NOW before any changes.22 Yes → Proceed to profiling.2324No optimization without baseline measurement. No exceptions. Violating the letter of this process IS violating the spirit.2526---2728## MANDATORY FIRST STEP2930**TodoWrite:** Create items for each phase below.3132**Never skip measurement:**33- 70% of "obvious" bottlenecks are wrong — Profile first34- 40% of optimizations without baseline cause regressions35- Production monitoring dashboards are NOT a substitute for a controlled baseline3637---3839## Process: BASELINE → PROFILE → STRATEGY → IMPLEMENT → VALIDATE4041### 1. Baseline Measurement (BEFORE any code changes)4243Record **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.4445### 2. Bottleneck Analysis (PROFILE, don't guess)4647- Profile with appropriate tool (see above)48- Identify slowest operation with **specific timing and % of total**49 - e.g., "orders query = 3.1s, 78% of total request time"50- Determine root cause (N+1 queries, missing index, blocking I/O, serialization)5152→ Profiling complete → Does result match initial assumption?53 No → Am I tempted to trust my assumption over the data? → STOP. Trust the profiler. Implement based on profiling data, not assumption.54 Yes → Implement based on profiling.5556### 3. Optimize and Validate5758- Evaluate 2-3 approaches with tradeoffs. State expected improvement.59- Implement minimal change — fix the measured bottleneck only60- **Re-measure with same tool, same conditions** as step 161- Compare before/after with specific numbers. Check no regressions.62- Record results in PR description with tool, conditions, and numbers6364---6566## Red Flags — STOP If You Think Any of These6768| Thought | Reality |69|---------|---------|70| "Bottleneck is obvious, skip profiling" | 70% wrong without data. Profile first. |71| "We'll measure after" | Can't validate without before. Measure NOW. |72| "Manual testing / curl is enough" | Need reproducible metrics, not feelings. |73| "Production dashboards = baseline" | Different conditions, not controlled. Measure directly. |74| "Senior dev says cache everything" | That's a hypothesis, not a diagnosis. Profile first. |75| "Already changed the code, too late" | Roll back, measure old code, re-apply, measure again. |76| "No time to profile" | 15 min profiling saves hours of wrong-direction work. |77| "I've seen this pattern before" | This system is different. Measure THIS system. |7879---8081## What To Do When You Skipped Baseline8283If you already made changes without measuring:84851. **Do NOT rationalize retroactive baselines** (production dashboards, "estimates")862. **Git stash or branch** your changes873. **Measure the old code** with proper tooling under controlled conditions884. **Re-apply your changes**895. **Measure again** with identical tool + conditions906. **Now** you have a valid before/after comparison9192This costs 30-60 minutes. Shipping unvalidated "performance improvements" costs trust, debugging time, and potential regressions.
pvillega