performance-optimization— agent skill

Overview

Premature optimization is the root of all evil. But ignoring performance until it's a crisis is equally harmful. This skill enforces data-driven optimization: profile first, optimize the bottleneck, measure the improvement.

When to Use

• When performance issues are reported in production
• Before optimizing any code (to ensure you're optimizing the right thing)
• When reviewing changes that touch performance-sensitive paths

Process

Step 1: Measure the Baseline

1. Reproduce the performance issue reliably.
2. Measure current performance: latency p50/p95/p99, throughput, memory, CPU.
3. Profile to find the actual bottleneck — not where you think it is.
4. Write the performance test you'll use to validate improvement.

Verify: You have concrete baseline numbers, not gut feelings.

Step 2: Identify the Real Bottleneck

1. Use profiling tools: flame graphs, CPU profiles, memory profiles.
2. Find the top 3 hotspots by actual execution time (not lines of code).
3. The bottleneck is rarely where you expect it to be. Trust the data.

Verify: Bottleneck identified by profiling data, not assumption.

Step 3: Optimize Only the Bottleneck

1. Fix only the profiled bottleneck — nothing else.
2. Common optimizations by type:

• CPU: Algorithmic improvement (O(n²) → O(n log n)), caching, batching
• Memory: Streaming instead of buffering, object pooling, lazy loading
• I/O: Connection pooling, N+1 query elimination, caching, async/parallel calls
• AI: Prompt caching, batch inference, smaller models for simpler tasks

Verify: Change targets the profiled bottleneck, not speculative improvements.

Step 4: Measure the Improvement

1. Run the same performance test from Step 1.
2. Compare before vs. after metrics.
3. If improvement < 20%: the optimization may not be worth the complexity.

Verify: Improvement measured with the same test harness as baseline.

Common Rationalizations (and Rebuttals)

Verification

• [ ] Baseline metrics captured before any optimization
• [ ] Bottleneck identified by profiler (not assumption)
• [ ] Optimization targets only the profiled bottleneck
• [ ] Improvement measured with same test harness
• [ ] Before/after numbers documented

References

• references/performance-checklist.md
• observability skill