Performance Skill

---
name: performance-optimization
description: Diagnose and fix performance problems. Use when something is slow, when the user mentions latency, memory, load time, or throughput, or when asked to optimize code.
---

# Performance Optimization

No optimization without measurement. An intuition about what is slow is a hypothesis, and in performance work intuitions are wrong often enough that acting on them directly wastes most of the effort spent on this kind of task.

## Before touching anything

Establish four things. Refuse to proceed without them:

1. **The metric.** What exactly is slow: p50 or p99 latency of what operation, memory at what point, throughput under what load. "The app feels slow" is not a metric.
2. **The baseline.** The current number, measured, with the conditions recorded: data size, hardware, concurrency, cache state. Written down, because you will need it to prove the change worked.
3. **The target.** What number is good enough, and why that number. Optimization without a stopping condition never stops.
4. **The reproduction.** How to trigger the slow path on demand.

If any is missing, get it first. Say so plainly rather than starting to optimize.

## Profile, do not guess

Run a profiler, or add timing around the stages of the operation. Report where the time actually goes as a breakdown.

Look for the shapes that dominate real systems before looking at code efficiency:
- **Waiting**, not computing: database round trips, network calls, disk, lock contention. Most slow software is waiting.
- **N+1 patterns**: a query, request, or file read inside a loop.
- **Doing work that is thrown away**: computing what is not used, fetching columns nobody reads, rendering what is not visible, serializing data that gets discarded.
- **Repeating identical work** with no cache.
- **The wrong algorithmic shape** on data that has grown: a linear scan inside a loop, sorting repeatedly, an unindexed lookup.
- **Allocation churn** and copying large structures.

Only after the profile points somewhere is reading that code worth doing.

## Change one thing

For each optimization:
1. State the hypothesis: this is slow because X, so changing Y should reduce Z by roughly this much.
2. Make the smallest change that tests it.
3. Measure under the same conditions as the baseline.
4. Report the actual number against the prediction, including when the change did nothing or made it worse. Those results are information, not failures.
5. Keep it only if the gain justifies the complexity it adds.

Never bundle several optimizations into one measurement. You will not know which one worked, and one of them is usually neutral while another is negative.

## Correctness is not negotiable

Run the tests after every change. A faster wrong answer is not an optimization. Watch specifically for caching that goes stale, concurrency introduced to overlap work, and edge cases eliminated along with the slow path.

## Report

The baseline, the profile, each change with its measured effect, the final number against the target, what you tried that did not help, and what remains on the table with its estimated cost and benefit.

Say plainly when the remaining work is not worth it. Stopping at good enough is the correct outcome, and continuing past it is how a performance task becomes a rewrite.