| name | software-ios-runtime-debugging |
| description | Proves iOS build/install/launch truth and triages hangs, crashes, jank, memory kills, and stale builds. Use when simulator, bundle, or runtime performance state is in doubt. |
| compatibility | Portable core. Works on Claude Code and Codex. |
| version | 1.1 |
| last_validated | 2026-07-11T00:00:00.000Z |
Native iOS Runtime Debugging
Use this skill when the core problem is not app architecture or visual design, but runtime truth: did the current binary build, install, launch, and render on the intended simulator or device — and once that's proven, is the live complaint a hang, a crash, jank, a memory kill, or a launch-time regression?
This skill owns stale-build suspicion, simulator drift, malformed .app bundles, missing executables, XcodeGen resource packaging mistakes, and the proof loop required before trusting screenshots, UI behavior, or downstream API/auth debugging. It also owns classifying and diagnosing live runtime performance and stability complaints once that proof exists: hangs and watchdog kills, crash symbolication, jank against frame budgets, Jetsam/memory pressure, and launch-time measurement traps.
Quick Reference
| Symptom | First Move | Notes |
|---|
| Screenshot does not match source | Uninstall -> install -> launch | Assume stale app first |
| Tool cannot read a simulator screenshot temp path | Re-capture from the current simulator | Temp screenshot files expire or move. Do not treat a missing temp path as invalidating the user's visible report |
| Install says app is missing executable | Inspect built .app bundle | Verify Info.plist and executable path before touching Swift |
| Simulator behaves inconsistently | Prove destination, boot, install, launch state | Do not debate UI until runtime truth exists |
| XcodeBuildMCP is unavailable | Fall back to xcodebuild, simctl, xcresulttool | Switch immediately |
| Auth appears to succeed but next screen is unauthenticated | Inspect token persistence and auth propagation after fresh launch | Do not redesign UI first |
| Push works on Xcode build but fails on TestFlight | Inspect archived entitlements and newest backend device row | Wrong APNs environment is more likely than feature-code regression |
APNs returns BadDeviceToken for older installs | Check device-row environment and staleness first | Often stale tokens or env mismatch, not a current-device blocker |
Push tap opens to black screen, freeze, or _performBlockAfterCATransactionCommitSynchronizes | Start at references/swift-concurrency-crash-triage.md; web-search the exact symbol before any code review | Known root cause family: nonisolated async UN delegate + nested MainActor.run, bare Task { } in @MainActor class, actor → @MainActor round-trip, @Sendable async closure, or SCNView updateUIView scene reassign. Separate transport proof from push-open proof: if APNs accepted delivery and the banner appeared, the bug is app-side |
| App stuck on a stale binary after |
When to Use This Skill
Use this skill to:
- Prove a fresh uninstall/install/launch loop for a native iOS app
- Diagnose stale installs or stale screenshots in simulator-driven workflows
- Inspect built
.app bundles when installation fails
- Debug simulator boot, shutdown, destination, and launch-state drift
- Investigate XcodeGen, resource packaging, bundle executable, or
Info.plist path problems
- Establish runtime truth before routing to feature implementation, design, or test skills
- Classify a live complaint as a hang, a crash, jank, a memory (Jetsam) kill, or a launch-time regression before choosing a fix
- Read Instruments, MetricKit, or crash-symbolication output and judge whether a lab fix will actually move field metrics
Core Workflow
- Discover the project entrypoint: workspace or project, scheme, configuration, destination, and bundle ID.
- Check tool reality:
use XcodeBuildMCP only if it is actually callable in the current runtime.
- Build the app with the simplest reproducible command.
- Inspect the built
.app:
verify Info.plist, executable name, and expected bundle contents.
- Remove stale installs:
uninstall the app from the target simulator or device.
- Install the freshly built bundle.
- Launch the freshly installed app and capture proof:
screenshot, UI hierarchy, launch logs, and a target-screen-specific marker when isolating a route.
- Only after the app is freshly running, debug feature behavior, design, auth, or API issues.
- For push issues, also prove the binary origin (Xcode debug vs TestFlight), the signed APNs entitlement on archive builds, and the newest backend device-row environment before chasing app logic.
- Treat transport proof and push-open proof as separate gates: APNs success and a visible banner do not prove tapping is safe.
- Route onward:
ASCII Flow
iOS runtime failure
-> Capture exact Xcode, iOS, device, build, repro, and logs
-> Prove clean build, install, launch, and current binary
-> Classify: crash, hang, UI, concurrency, persistence, network, or release
-> Inspect debugger, logs, Instruments, and screenshot evidence
-> Patch the smallest failing path
-> Rerun same repro and preserve before/after proof
Runtime Proof Loop
- Prefer one bounded loop:
discover -> build -> inspect bundle -> uninstall -> install -> launch -> capture evidence
- If any step fails, stop there and fix that layer before moving deeper.
- Do not trust screenshots from a simulator session that has not been tied to the current build.
- Do not trust “build succeeded” on its own; install and launch proof still matter.
- Do not stop on an unreadable temp screenshot path. Re-capture a screenshot, inspect the UI tree, or use the user's exact visible symptom to drive a focused source-level check.
- Verify isolated launch hooks at three levels: the env reached the process, the intended app branch executed, and the target screen is present through a screen-specific accessibility marker.
- If a screenshot or UI tree contradicts the expected launch hook, inspect the process env (
ps eww) and then verify the marker before trusting the capture.
Agent-Friendly Scaffold (Preventative)
Most stale-build, "cannot find X in scope", and unparseable-test-output symptoms in this skill are downstream of an Xcode project that was never set up for agents. The AppCreator pattern (Paul Solt, @PaulSolt) is the canonical recipe for scaffolding new iOS projects so agents stop generating those symptoms in the first place.
- Pattern: ship four properties together; each one breaks if removed.
- Buildable folders — agents add
.swift files by writing to disk; the project picks them up without pbxproj regeneration.
- Warnings-as-errors — surfaces deprecated APIs during the agent's own build/fix loop instead of at code review.
Makefile as the single entrypoint — make build, make run, make test. Agents do not need to learn xcodebuild flag combinations per project.xcbeautify wrapping every xcodebuild invocation — output stays parseable; agent does not choke on the 10–50k line wall.
- Anti-pattern: any one of these alone. Buildable folders without warnings-as-errors lets the agent ship deprecated code.
xcbeautify without a Makefile keeps the flag-juggling problem. A Makefile over a non-buildable-folder project means every new file still needs xcodegen or pbxproj surgery.
- Recipe (existing repo): add
Makefile first (wrap whatever build command already works) → wire xcbeautify into that target → switch project to buildable folders → flip warnings-as-errors last (it will fail until earlier deprecations are cleaned up). Source: https://super-easy-apps.kit.com/app-creator
For diagnostic patterns when the project is already mis-scaffolded, see the Quick Reference rows on xcodegen regeneration, target membership, and xcbeautify/-quiet output filtering.
Stale-Build Heuristics
| Symptom | Suspect | Action |
|---|
| UI doesn't match current source | Stale install | Remove installed app; reinstall fresh build |
| App shows old screen after rebuild | Cached install | Remove + reinstall; inspect install logs |
| Build succeeded but app looks old | Stale DerivedData or incremental build error | Check install logs; do not keep editing feature code |
| Simulator already running, UI state surprising | Previous simulator session | Re-prove install and launch before reasoning about app state |
| Push works on Xcode build, fails on TestFlight | APNs environment mismatch | Local → sandbox; TestFlight / App Store → production; verify per-device row |
| Transport works, app freezes or crashes on push tap | Notification-open path: delegate isolation, route staging, off-main mutation | Route to swift-concurrency-crash-triage.md |
dataCorrupted + <!DOCTYPE html> response | API routing / auth bug | Log URL, curl it; do not conflate with push-open crashes |
| Route state updates but destination never appears | Presentation hook not reached | Use a direct presentation hook to prove the screen in isolation |
| Simulator unresponsive (CoreSimulatorService errors) | Simulator service crashed | Switch to generic/platform=iOS for compile-only verification |
See references/stale-build-triage.md.
Packaging and Bundle Health
- When installation fails, inspect the built
.app bundle directly.
- Confirm:
Info.plist has expanded values, not unresolved placeholders- the executable exists at the path referenced by the bundle metadata
- expected resources are copied as resources, not malformed folder references
- If the error mentions missing bundle executable, treat it as a packaging issue first.
See references/xcodegen-resource-packaging.md.
Runtime Performance Triage
Once build/install/launch truth is established, a live complaint still needs to be classified before you touch code. Hang, watchdog kill, jank, Jetsam kill, and launch-time regression have different evidence and different fix ladders — do not default to "read the code" until the failure class has a name.
- Walk the triage order: terminated-with-crash-log → terminated-with-
0x8badf00d/watchdog → alive-but-unresponsive (hang) → alive-and-responsive-but-stuttering (jank) → disappeared-with-no-crash-log (Jetsam) → slow-to-first-frame (launch).
- Watch for the two most common misdiagnoses: blaming "main thread blocked" when it's priority inversion on a lower-QoS thread holding a shared lock, and trusting a single launch-time sample that may have been prewarmed.
- Instruments (Xcode 26-era), MetricKit, hang/watchdog thresholds, Jetsam behavior, frame-budget math, crash symbolication, LLDB workflows, thermal-state handling, and launch-time optimization are covered in depth in references/runtime-performance-triage.md — including which of these categories the Simulator cannot faithfully reproduce, and why lab evidence alone should never close out a field-facing performance fix.
Archive And APNs Validation
- Validate the exact
.xcarchive selected for upload before blaming runtime code. Avoid generic find ... .app | tail -1 shortcuts when multiple archives or export folders may exist:
codesign -d --entitlements :- "$APP" 2>/dev/null
security cms -D -i "$APP/embedded.mobileprovision" | plutil -p - | grep -A2 aps-environment
- Pass condition for a TestFlight/App Store archive:
aps-environment = production in the archived app entitlementsget-task-allow = falseaps-environment = production in the embedded provisioning profile
- If
aps-environment = development or get-task-allow = true, the archive is still development-signed. If those values are correct but validation fails, inspect generated plist metadata next.
- When push debugging crosses release channels, separate token-registration truth from transport truth. A common iOS/TestFlight failure is: many sandbox deliveries succeed, the only production delivery fails with
BadDeviceToken, and the phone receives nothing. Treat that as a stale-registration or invalid-production-token problem first, not as proof that APNs transport or signing is generally broken.
- Recovery sequence for mixed sandbox/production device state:
- Deactivate stale iOS device rows for the affected user.
- Uninstall local/debug builds and the TestFlight build.
- Reboot the physical iPhone.
- Reinstall from TestFlight.
- Open the app, sign in, allow notifications, then cold-reopen once.
- Confirm the newest active backend device row is
push_environment = production before re-sending.
- When validating backend send results, require both a successful APNs delivery with
environment = production and actual receipt on the TestFlight-installed phone. Transport success alone is not the end of the investigation.
XcodeGen and Resource Packaging
- If the repo generates Xcode projects, inspect the generator spec before blaming Swift code.
- Wrong resource declarations can create bundles that build but do not install correctly.
- Resource-folder copies, malformed folder references, or unresolved build settings often surface as install-time failures, not compile-time failures.
Project File Discovery
When a project uses XcodeGen with sources: [path: AppName], all .swift files in that directory tree are auto-discovered — but only when the project is regenerated.
Symptom: cannot find 'MyNewView' in scope after creating a new Swift file, even though the file exists on disk.
Fix: Run the project's generation script (typically scripts/generate-xcodeproj.sh) or xcodegen generate directly. The .xcodeproj/project.pbxproj will be updated with the new file references.
Common pattern: After creating multiple new files in a feature directory, regenerate once, then build.
For repos managed directly through .xcodeproj/project.pbxproj, new Swift files may exist on disk but still be invisible to the build until they are added to the correct target membership. In that case, edit the project file or use Xcode to register the file before investigating feature code.
Route Elsewhere
- Use software-ios-native once runtime truth is established and the task becomes feature implementation, rewrite planning, or SwiftUI architecture.
- Use software-ios-design once the screen is confirmed to come from a fresh build and the task is visual hierarchy, typography, materials, or HIG compliance.
- Use qa-testing-ios once the app is buildable and installable and the task becomes test execution,
xcresult, destinations, or flake control.
- Use software-mobile for platform choice, Android, or cross-platform tradeoffs.
Navigation
References
Templates
Related Skills
Fact-Checking
- Known bugs, regressions, framework/compiler/runtime footguns, and version-specific crash or workaround guidance must be verified against current primary web sources before being treated as current fact.
- Prefer Apple documentation for
xcodebuild, simctl, and bundle structure behavior.
- Prefer upstream XcodeBuildMCP docs for tool names, CLI commands, and config keys.
- Treat repo-specific build, scheme, bundle ID, and generator behavior as local facts that must be discovered, not assumed.
- Instrument names, hardware-gated feature availability (e.g., Processor Trace chip requirements), and exact watchdog timings change across Xcode/iOS releases — re-verify against current Apple release notes rather than trusting a fixed number from this skill. Jetsam memory-limit figures are explicitly empirical, not Apple-published, and should be re-derived from device behavior (
os_proc_available_memory, jetsam event reports), not hardcoded.
Learnings Loop
Before applying this skill on a non-trivial task, read learnings.consolidated.md in this directory (and learnings.md if present).
After applying it, if you encountered a pattern worth remembering, a mistake worth preventing, or a domain fact that surprised you, append one dated bullet to learnings.md via agents-skills-feedback-loop/scripts/append_learning.py. Do not modify SKILL.md itself.
