iOS Performance Profiling

iOS Performance Profiling

Purpose

Use this skill to choose the right profiling workflow, gather evidence, interpret performance signals, and recommend validation before claiming that an optimization worked.

This skill is a profiling router and evidence workflow. It should not replace more specific skills for launch performance, SwiftUI performance, Swift Concurrency performance, perceived performance, or Swift runtime costs.

When to use this skill

Use this skill when the task involves:

• choosing an Instruments template or profiling workflow;
• interpreting traces, screenshots, XCTest metrics, MetricKit payloads, Organizer data, logs, or signposts;
• diagnosing hangs, animation hitches, CPU spikes, memory growth, leaks, disk I/O, network latency, power usage, or production regressions;
• designing a before/after measurement plan;
• adding signposts or performance tests;
• checking whether a proposed optimization is supported by evidence.

When not to use this skill

Do not use this skill as the primary skill for:

• app startup architecture or launch-critical work unless the task asks how to profile, measure, or verify launch performance;
• SwiftUI invalidation, identity, layout, or scrolling fixes unless the task asks which profiling evidence to collect;
• Swift Concurrency design or actor isolation unless the task asks how to profile task behavior, actor hopping, or executor-related latency;
• perceived performance, loading states, skeletons, optimistic UI, or feedback design unless the task asks how to validate perceived latency;
• Swift runtime, ARC, allocation, existential, generic, dispatch, or linking costs unless the task asks how to measure them.

Prefer the more specific skill when the user already knows the domain and needs a fix rather than a measurement workflow.

Core principle

Evidence before optimization.

Use this loop:

Symptom -> reproducible scenario -> correct tool -> trace or metric -> hypothesis -> focused fix -> re-measure

Do not claim that a change improved performance unless there is a validation path. If evidence is missing, say what is not proven yet and what should be measured next.

Capability check

Before recommending or running a real profiling workflow, check what is actually available.

Ask or infer:

• Is there a buildable Xcode project, workspace, scheme, and target?
• Is profiling possible on a real device, or only in Simulator?
• Is a Release or release-like configuration available?
• Is the scenario reproducible with stable data and stable app state?
• Are Instruments traces, screenshots, MetricKit payloads, Organizer screenshots, logs, or XCTest results available?
• Can traces or reports be shared as artifacts?
• Is the task asking for a profiling plan, a code review, or interpretation of existing evidence?

If tooling or artifacts are unavailable, provide a measurement plan instead of pretending to have profiled the app.

Measurement baseline

Prefer profiling with:

• real device over Simulator for UI, launch, power, memory pressure, thermal behavior, and production-like responsiveness;
• Release or release-like builds over Debug builds;
• repeated runs over a single measurement;
• stable input data and deterministic scenarios;
• device and OS information included in the report;
• signposts around app-specific operations when system-level traces are too broad.

Use Simulator only when the question is about relative local investigation and the limitation is clearly stated.

Tool selection

Choose the tool from the symptom, not from a favorite workflow.

When the signal is app-specific and not visible enough in system instruments, add os_signpost or OSSignposter around the operation.

Cross-skill routing

Use this skill to select and validate the profiling path. Route deeper domain reasoning to narrower skills when needed:

• Use ios-launch-performance when the evidence points to pre-main work, dyld, static initializers, app initialization, root scene construction, first frame, first interaction, SDK startup, database warmup, or launch-critical dependency chains.
• Use swiftui-performance when the evidence points to broad state reads, unnecessary invalidation, unstable identity, expensive layout, row complexity, scrolling behavior, or repeated body work.
• Use swift-concurrency-performance when the evidence points to task explosions, actor hopping, MainActor bottlenecks, missing cancellation, AsyncSequence pressure, executor behavior, or async work causing UI latency.
• Use ios-perceived-performance when the evidence shows the app is technically doing work, but the user-visible problem is lack of feedback, poor loading states, late progressive rendering, or perceived latency.
• Use swift-runtime-performance when the evidence points to allocation churn, ARC traffic, existentials, generics, dynamic dispatch, copy-on-write, bridging, linking, or runtime-level costs.

Do not duplicate the deep guidance from those skills here.

Profiling workflow

1. Identify the user-visible symptom.
2. Define the exact scenario that reproduces it.
3. Choose the primary profiling tool from the symptom.
4. Record the device, OS, build configuration, data set, and run count.
5. Capture the strongest signal: stack, frame hitch, allocation growth, retain path, network waterfall, disk write, wakeup, or production metric.
6. Separate what the data proves from what it only suggests.
7. Form one or two ranked hypotheses.
8. Recommend the smallest focused fix or the next inspection step.
9. Re-measure with the same scenario.
10. Suggest a regression guard when the issue is important enough.