Performance

Fast means two numbers: the first frame after a key press shows in under 100 ms, and nothing on the main thread blocks for more than 50 ms. Every change in this skill starts and ends with a measurement, so you know it helped. Symptom-by-symptom fixes are in recipes.md. For video, audio, camera, Metal, or large image pipelines, also read gpu-media.md.

The loop

reproduce -> measure (release build) -> find the line -> fix -> measure again -> commit with the numbers

1. Reproduce. Write the exact steps, or add a probe command to the debug bridge (test-mac-app skill) that runs the slow action and logs the time of each step.

2. Measure the release build. Debug Swift is 3 to 10 times slower and points at the wrong code.

3. Find the line. Pick the tool for the symptom:

   Symptom	Tool
   App freezes, spinning pointer	sample <App> 5, then read the main thread stack
   Slow action	Time Profiler: xcrun xctrace record --template 'Time Profiler' --attach <App> --time-limit 10s
   Short freezes while typing or dragging	--template 'Hangs'
   Stutter while moving or animating	--template 'Animation Hitches'
   Memory grows	footprint <App>, leaks <App>, --template 'Allocations'
   Fan, battery	--template 'Energy Log', look for timers and polling

   Read traces as text, not in the Instruments GUI: see "Measuring" in recipes.md. Delete every .trace after reading. A trace stores the app's full environment, and an app opened from an agent's shell inherits that shell's tokens. Never commit or share one.

4. Fix with the matching recipe.

5. Measure again with the same steps. Put before and after in the commit message: "Picker opens in 40 ms, was 600 ms".

The rules that fix most problems