---
name: apple-performance-memory
description: "Profile and diagnose Apple app latency, hangs, SwiftUI update cost, or memory growth. Use for Instruments, trace or memgraph analysis, and before/after performance evidence."
---

# Apple Performance / Memory

## Purpose

Use this skill when the question is runtime cost, not merely build correctness. Start with code and scenario clarity, then pick the smallest trace that answers the question.

## Workflow

1. Define the scenario.
   - launch, first screen, scroll, navigation, search, import/export, HealthKit sync, model generation, background work, watch handoff, or memory growth
   - same scheme, destination, configuration, data, and steps for before/after comparisons

2. Inspect code first.
   - SwiftUI body churn, expensive computed properties, broad Observation invalidation, unstable IDs, nested lists, image decoding, synchronous work on the main actor
   - retain cycles, long-lived tasks, unbounded caches, NotificationCenter/KVO/timer ownership, task cancellation, and actor isolation problems

3. Pick the proof.
   - Instruments or `xctrace` for CPU, hangs, allocation, leaks, and launch
   - Top Functions for hot-stack narrowing
   - ETTrace helpers for iOS Simulator latency and stack comparison
   - dSYM collection when traces need symbolication
   - memgraph helpers for retained objects and leaks
   - Foundation Models Instrument for prompt, response, token, and tool-call behavior
   - XcodeBuildMCP coverage/log workflows when the issue is tied to tests or runtime logs

4. Run the narrow command.
   - Keep raw trace files out of git unless the repo explicitly stores performance artifacts.
   - Create a private per-run directory before collecting evidence: `RUN_DIR="$(mktemp -d /private/tmp/apple-profile.XXXXXX)" && chmod 700 "$RUN_DIR"`.
   - Treat Foundation Models traces, prompts, responses, and tool-call payloads as sensitive: minimize capture, do not paste raw content into tickets or commit it, and delete the run directory after the evidence is summarized unless retention is explicitly approved.
   - Preserve the exact command, destination, device, OS, build configuration, and app version.

5. Fix and compare.
   - Make one causal change at a time where possible.
   - Re-run the same scenario.
   - Report before/after evidence and residual risk.

## Bundled Helpers

- `scripts/analyze_flamegraph_json.py`
- `scripts/collect_ios_dsyms.sh`
- `scripts/capture_sim_memgraph.sh`
- `scripts/summarize_memgraph_leaks.py`

## References

- `references/swiftui/`