| name | performance |
| user-invocable | false |
| description | Profiling methodology and optimization strategy for performance work. Use when the user asks to "make this faster", "optimize", "profile", "reduce latency", "fix slow", "improve throughput", or when investigating performance regressions. |
Performance as Measurement
Overview
Optimize what you've measured, not what you suspect. Performance work without profiling is superstition. Measure first, hypothesize second, optimize third, measure again.
The Performance Loop
- Define the goal, What metric matters? Latency, throughput, memory, startup time?
- Measure the baseline, Quantify current performance with reproducible benchmarks
- Profile, Identify where time and resources actually go
- Hypothesize, What change would improve the bottleneck?
- Optimize, Make one change
- Measure again, Did it help? By how much? Any regressions elsewhere?
Never skip from step 1 to step 5.
For concrete profiler commands and a step-by-step run of this loop per language, see references/profiling-checklist.md.
Trade-off Framework
Every optimization trades one resource for another. Make the trade explicit.
| Trade-off | Example |
|---|
| Latency vs. throughput | Batching increases throughput, raises individual latency |
| Memory vs. CPU | Caching trades memory for fewer computations |
| Simplicity vs. speed | Hand-rolled loops beat abstractions but obscure intent |
| Startup vs. runtime | Lazy loading delays startup cost to first use |
| Bandwidth vs. latency | Compression saves bandwidth, costs CPU time |
| Consistency vs. speed | Eventual consistency is faster than strong consistency |
Ask: "Which resource is scarce in this context?" Optimize for the scarce one.
Profiling Strategy
Where to Look
Start with the outermost measurement, narrow inward:
- End-to-end timing, Total wall-clock time for the operation
- Component breakdown, Which phase takes the most time?
- Hot path analysis, Which functions dominate the profile?
- Allocation analysis, Where is memory allocated and freed?
What Tools Reveal
| Tool type | Reveals | Misses |
|---|
| Wall-clock timer | Total duration | Where time is spent |
| CPU profiler | Hot functions | I/O waits, lock contention |
| Memory profiler | Allocations, leaks | Cache effects |
| Flame graph | Call hierarchy costs | Inlined functions |
| Tracing | Request flow, latency | Aggregate behavior |
| Load testing | Throughput limits | Root cause of limits |
Use at least two tool types. A CPU profiler won't find a database bottleneck.
Common Bottleneck Patterns
I/O Bound
Symptoms: Low CPU usage, high wait times, slow under load.
Causes: Synchronous I/O, N+1 queries, unbatched requests, no connection pooling.
Remedies: Batch operations, add caching, use async I/O, pool connections.
CPU Bound
Symptoms: High CPU usage, scales with input size, unaffected by I/O improvements.
Causes: Inefficient algorithms, unnecessary computation, poor data structures.
Remedies: Better algorithms first (O(n) beats optimized O(n^2)), then micro-optimize the hot path.
Memory Bound
Symptoms: Growing memory usage, GC pauses, OOM errors, cache thrashing.
Causes: Unbounded caches, leaked references, large intermediate allocations, fragmentation.
Remedies: Bound caches (LRU), stream instead of buffer, pool allocations, reduce object size.
Contention Bound
Symptoms: Low individual resource usage but poor throughput under concurrency.
Causes: Lock contention, shared mutable state, thread pool exhaustion, connection limits.
Remedies: Reduce critical section scope, use lock-free structures, partition state, increase pool size.
Anti-Patterns
Premature optimization, Optimizing before measuring. The bottleneck is never where you think.
Micro-benchmarking in isolation, Benchmarking a function outside its real context misses cache effects, GC pressure, and contention.
Optimizing the wrong metric, Reducing P50 latency when users complain about P99. Improving throughput when the problem is startup time.
Death by a thousand cuts, No single bottleneck, just accumulated inefficiency. Profile holistically, not function-by-function.
Caching without invalidation strategy, Cache speeds reads but stale data causes correctness bugs. Define TTL and invalidation before adding a cache.
Output Format
When analyzing performance:
## Performance Analysis
### Goal
[Specific metric and target: "Reduce API P99 latency from 800ms to 200ms"]
### Baseline
[Current measurements with methodology]
### Profile Summary
[Where time/memory/resources go, ranked by impact]
### Recommendations
1. [Change] — [Expected improvement] — [Trade-off]
2. [Change] — [Expected improvement] — [Trade-off]
### Not Optimizing
[What was considered but rejected, and why]
Knuth's Reminder
"Programmers waste enormous amounts of time thinking about, or worrying about, the speed of noncritical parts of their programs, and these attempts at efficiency actually have a strong negative impact when debugging and maintenance are considered."
Optimize the critical 3%, not the other 97%.
See Also
/debugging: Performance regressions are bugs; profiling is debugging for speedskills/FRAMEWORKS.md: Full framework indexRECIPE.md: Agent recipe for parallel decomposition (2 workers)
