/ios-runtime-forensics-workflow

name: ios-runtime-forensics-workflow
description: Capture and interpret reproducible iOS Simulator performance and memory evidence. Use when an iOS issue needs ETTrace/symbolication, a memgraph, leak ownership traces, or before/after runtime proof rather than a code-only guess.

iOS Runtime Forensics Workflow

Purpose

Provide two explicit evidence modes for a reproducible iOS Simulator issue: `performance-trace` for focused ETTrace/symbolicated latency or CPU work, and `memory-graph` for retained-object and leak ownership analysis. This skill owns evidence shape, not normal app build, launch, or UI driving.

When To Use

• Use `performance-trace` for launch/runtime latency, CPU-heavy stacks, or comparison traces.
• Use `memory-graph` for leaks, retain cycles, memory growth, or objects that should release after a known interaction.
• Route simulator discovery, build, install, launch, logs, screenshots, and UI driving to `xcode-build-run-workflow`.

Single-Path Workflow

1. Apply the Apple docs gate through `explore-apple-swift-docs`. Confirm the current Xcode/Simulator evidence mechanism before acting. 2. Define one reproduction, start/stop boundary, target app build, simulator UDID, OS, Xcode version, and expected release or latency behavior. 3. Select exactly one mode: `performance-trace` or `memory-graph`. Do not mix CPU and ownership conclusions in one unsupported capture. 4. For `performance-trace`, read `references/performance-trace-evidence.md`, capture a focused trace with matching symbols, and identify hot stacks only after symbolication. 5. For `memory-graph`, read `references/memory-graph-evidence.md`, drive the release-producing flow, capture a memgraph, inspect app-owned retained types, and follow ownership evidence to the retaining path. 6. Make the smallest root-cause change, then recapture the same flow on the same simulator where practical. 7. Report the exact capture boundary, tool/version context, what the artifact proves, what it does not prove, and the before/after delta.

Inputs

• reproducible simulator flow, target app/scheme, simulator UDID, and build configuration
• expected release/lifetime or performance boundary
• mode: `performance-trace` or `memory-graph`
• existing trace, memgraph, logs, screenshots, or symbol files when available

Outputs

• capture plan or artifact evidence with its scope and limitations
• app-owned hot stack or retaining ownership path when evidence supports it
• smallest remediation and same-flow recapture result

Guards and Stop Conditions

• Do not call a memory graph a leak proof until the expected lifetime and retaining path are established.
• Do not compare traces with different app builds, simulator/OS state, or workload boundaries as a regression result.
• Do not claim a symbolicated root cause from an unsymbolicated stack.
• Stop when the issue cannot be reproduced or a capture would include user-sensitive content without explicit approval.

Fallbacks and Handoffs

• Recommend `xcode-build-run-workflow` for all normal simulator execution and log/UI evidence.
• Recommend `xcode-testing-workflow` for Instruments, `xctrace`, test plans, and broader Xcode performance work.
• Recommend `swiftui-performance-audit` when the user first needs a code-first SwiftUI hypothesis.

References

• `references/performance-trace-evidence.md`
• `references/memory-graph-evidence.md`
• Recommend `references/snippets/apple-xcode-project-core.md` when the app needs reusable Xcode-project policy alongside simulator evidence work.