performance-optimization

name	performance-optimization
description	Systematic performance optimization with measurement-first methodology. Use when performance issues are identified, during review phase, or when building performance-critical features. Profile before optimizing.
version	1.0.0
permissions	["fs.read","fs.write","shell.exec","browser.inspect"]
triggers	[{"context":"performance issue"},{"context":"slow response times"},{"context":"optimization needed"},{"command":"/review"}]
platforms	["claude-code","cursor","gemini-cli","copilot","codex","opencode","windsurf","kiro"]
dependencies	["test-driven-development@^1.0.0"]
author	codehands-core
signed	true
tier	2

Overview

Performance optimization follows one iron rule: measure first, optimize second. Never optimize based on intuition. Profile, identify the bottleneck, fix it, measure again. Premature optimization is the root of all evil — but measured optimization is engineering.

When to Use

• When profiling reveals a measurable performance problem
• During /review phase for performance-sensitive code
• When building features with explicit performance requirements
• NOT speculatively ("this might be slow someday")

Process

1. Measure Current Performance

Before ANY optimization:

# Backend: Response time
time curl -s http://localhost:3000/api/endpoint

# Frontend: Lighthouse
npx lighthouse http://localhost:3000 --output=json

# Database: Query time
EXPLAIN ANALYZE SELECT ...;

Record the baseline. Without a baseline, you can't prove improvement.

2. Identify the Bottleneck

• Is it CPU? Memory? I/O? Network? Database?
• Use profiling tools appropriate to the stack
• The bottleneck is ONE thing. Find it before fixing anything.

3. Optimize the Bottleneck

Apply the fix with the smallest possible change. Common optimizations:

Problem	Solution
N+1 queries	Eager loading, DataLoader, batch queries
Missing index	Add database index on query columns
Unbounded query	Add LIMIT, implement pagination
Full table scan	Add WHERE clause, use index
Unnecessary re-renders	Memoization (React.memo, useMemo)
Large bundle	Code splitting, tree shaking, lazy loading
Uncompressed responses	Enable gzip/brotli compression
Synchronous blocking	Move to async/background job

4. Measure Again

Same measurement as Step 1. Compare to baseline. If improvement < 10%, reconsider whether the optimization is worth the complexity.

5. Document the Change

## Performance Optimization: [What]
- Baseline: 450ms p99 response time
- After: 85ms p99 response time
- Improvement: 5.3x faster
- Change: Added index on users.email column

Common Rationalizations

Rationalization	Reality
"I know this will be slow"	You don't — measure it. Developers are notoriously bad at predicting bottlenecks.
"Premature optimization is bad, so I shouldn't think about performance"	Premature optimization of the wrong thing is bad. Choosing an O(n²) algorithm when O(n) exists isn't "premature" — it's a mistake.
"The optimization is obvious, I don't need to measure"	Obvious optimizations sometimes make things worse (e.g., caching adding overhead for small datasets). Measure.

Red Flags

• Optimizing without a baseline measurement
• Optimizing code that isn't the bottleneck
• Adding caching without understanding the access pattern
• Micro-optimizing at the cost of readability
• No measurement after the change

Verification

• Baseline performance measured before optimization
• Bottleneck identified via profiling (not guessing)
• Optimization targets the actual bottleneck
• Performance measured after optimization (improvement confirmed)
• No regression in functionality (all tests pass)
• Optimization documented with before/after metrics

See Also

• references/performance-checklist.md — Quick-scan checklist
• codehands:frontend-ui-engineering — Frontend-specific performance
• codehands:code-simplification — When simplification improves performance