software-ios-runtime-debugging

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

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

1. Discover the project entrypoint: workspace or project, scheme, configuration, destination, and bundle ID.
2. Check tool reality: use XcodeBuildMCP only if it is actually callable in the current runtime.
3. Build the app with the simplest reproducible command.
4. Inspect the built .app: verify Info.plist, executable name, and expected bundle contents.
5. Remove stale installs: uninstall the app from the target simulator or device.
6. Install the freshly built bundle.
7. Launch the freshly installed app and capture proof: screenshot, UI hierarchy, launch logs, and a target-screen-specific marker when isolating a route.
8. 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.

9. Route onward:
   • visual hierarchy and HIG review -> software-ios-design
   • native feature or architecture work -> software-ios-native
   • test execution and xcresult triage -> qa-testing-ios

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.
  1. Buildable folders — agents add .swift files by writing to disk; the project picks them up without pbxproj regeneration.
  2. Warnings-as-errors — surfaces deprecated APIs during the agent's own build/fix loop instead of at code review.
  3. Makefile as the single entrypoint — make build, make run, make test. Agents do not need to learn xcodebuild flag combinations per project.
  4. 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

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 entitlements
  • get-task-allow = false
  • aps-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:
  1. Deactivate stale iOS device rows for the affected user.
  2. Uninstall local/debug builds and the TestFlight build.
  3. Reboot the physical iPhone.
  4. Reinstall from TestFlight.
  5. Open the app, sign in, allow notifications, then cold-reopen once.
  6. 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.