| name | performance-engineering |
| description | Measurement-first performance engineering in any language: profiling methodology, USE/RED/golden-signals triage, latency percentiles and tail latency, benchmarking discipline, complexity and memory analysis, caching, concurrency throughput, and the optimization order of attack. Use when something is "slow", before/while optimizing code, when designing performance budgets or load tests, or when reviewing changes claimed to improve performance. For SwiftUI rendering use swiftui; for GPU use metal.
|
| allowed-tools | ["Read","Glob","Grep","Bash"] |
Performance Engineering
IRON LAW: NO OPTIMIZATION WITHOUT A MEASUREMENT SHOWING THE BOTTLENECK,
AND A SECOND MEASUREMENT PROVING THE FIX. GUESSING IS FORBIDDEN.
Phase Workflow (gated — complete in order)
Phase 1 — Define
- Symptom, workload, environment, and a number: target metric + budget
(e.g., "p99 < 200 ms at 500 RPS", "cold start < 1.5 s").
- Percentiles, not averages: users experience the tail (p95/p99). Beware
coordinated omission in load tools (measure from intended start time).
Phase 2 — Measure
- Reproduce under realistic load and data volume.
- Triage with USE per resource (CPU/memory/disk/network: Utilization,
Saturation, Errors) and RED per service (Rate, Errors, Duration).
- Profile before reading code: CPU profiler/flame graph, allocation profiler,
I/O and query traces. The bottleneck is where measurement says it is — it
is usually not where intuition says.
Phase 3 — Fix (order of attack, highest leverage first)
- Don't do the work: cache, dedupe, precompute, lazy-load, early-exit.
- Do less work: better algorithm/data structure (see
algorithms),
batch round-trips (N+1 queries), reduce payloads.
- Do work elsewhere/later: async, background, off the critical path.
- Do work in parallel: Amdahl's law bounds the win to the parallelizable
fraction — compute the ceiling before parallelizing.
- Micro-optimize last: data layout/cache locality, allocation pressure,
SIMD — only with profiler evidence and only on hot paths (mechanics in
the
hardware-runtime skill).
Phase 4 — Verify & Guard
- Re-measure the same metric, same workload. Report before/after with units.
- Confirm no regression elsewhere (memory ↔ CPU tradeoffs are common).
- Add a benchmark or perf test in CI with a baseline so the win can't
silently rot.
Benchmarking Discipline
- Warm up; multiple iterations; report median + spread, not the best run.
- Fixed inputs, isolated machine state; pin versions.
- Compare like with like: same data, same build configuration (release mode).
- A microbenchmark that doesn't match the production access pattern is fiction.
Rationalization Table (STOP signs)
| If you think… | Reality |
|---|
| "This is obviously the slow part" | Profile it. Intuition is wrong more often than not |
| "This optimization can't hurt" | Unmeasured "optimizations" add complexity and bugs for ~0 gain |
| "Average latency looks fine" | Your p99 users are timing out |
| "We'll add metrics later" | Without baselines you can never prove improvement |
Related Skills
| Need | Skill |
|---|
| Algorithm/data-structure selection | algorithms |
| Cache behavior, false sharing, scheduling, atomics | hardware-runtime |
| SwiftUI rendering performance | swiftui (performance-audit) |
| Swift concurrency performance | swift (concurrency/performance) |
| GPU profiling | metal |
| Infra capacity/observability | system-architect |
| Performance-audit execution contract | planner (performance-audit template) |
