performance

1# Performance
2 
3Fast means two numbers: the first frame after a key press shows in under
4100 ms, and nothing on the main thread blocks for more than 50 ms. Every
5change in this skill starts and ends with a **measurement**, so you know it
6helped. Symptom-by-symptom fixes are in [recipes.md](recipes.md). For
7video, audio, camera, Metal, or large image pipelines, also read
8[gpu-media.md](gpu-media.md).
9 
10## The loop
11 
12```text
13reproduce -> measure (release build) -> find the line -> fix -> measure again -> commit with the numbers
14```
15 
161. **Reproduce.** Write the exact steps, or add a probe command to the
17   debug bridge (`test-mac-app` skill) that runs the slow action and logs
18   the time of each step.
192. **Measure the release build.** Debug Swift is 3 to 10 times slower and
20   points at the wrong code.
213. **Find the line.** Pick the tool for the symptom:
22 
23   | Symptom | Tool |
24   | --- | --- |
25   | App freezes, spinning pointer | `sample <App> 5`, then read the main thread stack |
26   | Slow action | Time Profiler: `xcrun xctrace record --template 'Time Profiler' --attach <App> --time-limit 10s` |
27   | Short freezes while typing or dragging | `--template 'Hangs'` |
28   | Stutter while moving or animating | `--template 'Animation Hitches'` |
29   | Memory grows | `footprint <App>`, `leaks <App>`, `--template 'Allocations'` |
30   | Fan, battery | `--template 'Energy Log'`, look for timers and polling |
31 
32   Read traces as text, not in the Instruments GUI: see "Measuring" in
33…