Performance Optimization

---
name: performance-optimization
description: "Measure, identify bottlenecks, fix, verify, and guard performance regressions. Use for web vitals, slow APIs, heavy notebooks/pipelines, or video/render workloads."
allowed-tools: Read, Glob, Grep
---

# Performance optimization

## Workflow

```
MEASURE -> IDENTIFY -> FIX -> VERIFY -> GUARD
```

Never optimize without a baseline.

## Measure first

| Domain | Signals |
|--------|---------|
| Web | LCP, INP, CLS, bundle size, waterfall |
| API/DB | p50/p95 latency, query plans, N+1 |
| Data/ML | wall time, memory peak, I/O wait |
| Media | frame time, encode throughput |

## Identify

- Profile before guessing (browser Performance, py-spy, query EXPLAIN)
- One bottleneck at a time; document hypothesis

## Fix patterns (common)

| Issue | Direction |
|-------|-----------|
| Large JS bundle | Code split, lazy routes, tree-shake |
| Render churn | Memoization only when measured; virtualize lists |
| Slow queries | Indexes, fewer round trips, pagination |
| Pandas hot path | Vectorize, polars, smaller dtypes |

## Verify

- Compare before/after with same workload
- Check regressions on adjacent metrics (memory, error rate)

## Guard

- Budget thresholds in CI or release checklist
- `gstack/benchmark` for web regressions when applicable

## Related

`gstack/benchmark`, `frontend-engineering/frontend-ui-accessibility`, `observability-slo`

See [reference.md](reference.md) for a performance review checklist.