1. Tool Overview

Tool	Purpose
`ios-profiler-start`	Start xctrace recording on a booted simulator or device. Captures CPU, hangs, and leaks. Optional: `app_process`, `template_path`.
`ios-profiler-stop`	Stop xctrace, export trace data to XML files (timestamped, persist on disk).
`ios-profiler-analyze`	Parse exported XML and return structured bottleneck payload (CPU hotspots, UI hangs, leaks).
`profiler-stack-query`	Drill into parsed data: hang stacks, function callers, thread breakdown, leak details.
`profiler-load`	List and reload previous trace sessions from disk for re-investigation.

2. Investigation Patterns

After ios-profiler-analyze surfaces findings, use profiler-stack-query to drill into root causes:

Hang detected → profiler-stack-query mode=hang_stacks for full native call chains → mode=function_callers for the suspected function → read native source.
CPU hotspot → profiler-stack-query mode=thread_breakdown for per-thread distribution → mode=function_callers for the dominant function.
Memory leak → profiler-stack-query mode=leak_stacks filtered by object_type for responsible frames and libraries.