iOS Build & Environment Router

You MUST use this skill for ANY build, environment, or Xcode-related issue before debugging application code.

When to Use

Use this router when you encounter:

• Build failures (BUILD FAILED , compilation errors, linker errors)

• Test crashes or hangs

• Simulator issues (won't boot, device errors)

• Xcode misbehavior (stale builds, zombie processes)

• Dependency conflicts (CocoaPods, SPM)

• Build performance issues (slow compilation)

• Environment issues before debugging code

Routing Logic

This router invokes specialized skills based on the specific issue:

1. Environment-First Issues → xcode-debugging

Triggers:

• BUILD FAILED without obvious code cause

• Tests crash in clean project

• Simulator hangs or won't boot

• "No such module" after SPM changes

• Zombie xcodebuild processes

• Stale builds (old code still running)

• Clean build differs from incremental build

Why xcode-debugging first: 90% of mysterious issues are environment, not code. Check this BEFORE debugging code.

Invoke: /skill axiom-xcode-debugging

2. Slow Builds → build-performance

Triggers:

• Compilation takes too long

• Type checking bottlenecks

• Want to optimize build time

• Build Timeline shows slow phases

Invoke: /skill axiom-build-performance

3. SPM Dependency Conflicts → spm-conflict-resolver (Agent)

Triggers:

• SPM resolution failures

• "No such module" after adding package

• Duplicate symbol linker errors

• Version conflicts between packages

• Swift 6 package compatibility issues

• Package.swift / Package.resolved conflicts

Why spm-conflict-resolver: Specialized agent that analyzes Package.swift and Package.resolved to diagnose and resolve Swift Package Manager conflicts.

Invoke: Launch spm-conflict-resolver agent

4. Security & Privacy Audit → security-privacy-scanner (Agent)

Triggers:

• App Store submission prep

• Privacy Manifest requirements (iOS 17+)

• Hardcoded credentials in code

• Sensitive data storage concerns

• ATS violations

• Required Reason API declarations

Why security-privacy-scanner: Specialized agent that scans for security vulnerabilities and privacy compliance issues.

Invoke: Launch security-privacy-scanner agent or /axiom:audit security

5. iOS 17→18 Modernization → modernization-helper (Agent)

Triggers:

• Migrate ObservableObject to @Observable

• Update @StateObject to @State

• Adopt modern SwiftUI patterns

• Deprecated API cleanup

• iOS 17+ migration

Why modernization-helper: Specialized agent that scans for legacy patterns and provides migration paths with code examples.

Invoke: Launch modernization-helper agent or /axiom:audit modernization

6. Build Failure Auto-Fix → build-fixer (Agent)

Triggers:

• BUILD FAILED with no clear error details

• Build sometimes succeeds, sometimes fails

• App builds but runs old code

• "Unable to boot simulator" error

• Want automated environment-first diagnostics

Why build-fixer: Autonomous agent that checks zombie processes, Derived Data, SPM cache, and simulator state before investigating code. Saves 30+ minutes on environment issues.

Invoke: Launch build-fixer agent or /axiom:fix-build

7. Slow Build Optimization → build-optimizer (Agent)

Triggers:

• Builds take too long

• Want to identify slow type checking

• Expensive build phase scripts

• Suboptimal build settings

• Want parallelization opportunities

Why build-optimizer: Scans Xcode projects for build performance optimizations — slow type checking, expensive scripts, suboptimal settings — to reduce build times by 30-50%.

Invoke: Launch build-optimizer agent or /axiom:optimize-build

8. General Dependency Issues → build-debugging

Triggers:

• CocoaPods resolution failures

• "Multiple commands produce" errors

• Framework version mismatches

• Non-SPM dependency graph conflicts

Invoke: /skill axiom-build-debugging

9. TestFlight Crash Triage → testflight-triage

Triggers:

• Beta tester reported a crash

• Crash reports in Xcode Organizer

• Crash logs aren't symbolicated

• TestFlight feedback with screenshots

• App was killed but no crash report

Why testflight-triage: Systematic workflow for investigating TestFlight crashes and reviewing beta feedback. Covers symbolication, crash interpretation, common patterns, and Claude-assisted analysis.

Invoke: /skill axiom-testflight-triage

10. App Store Connect Navigation → app-store-connect-ref

Triggers:

• How to find crashes in App Store Connect

• ASC metrics dashboard navigation

• Understanding crash-free users percentage

• Comparing crash rates between versions

• Exporting crash data from ASC

• App Store Connect API for crash data

Why app-store-connect-ref: Reference for navigating ASC crash analysis, metrics dashboards, and data export workflows.

Invoke: /skill axiom-app-store-connect-ref

11. Crash Log Analysis → crash-analyzer (Agent)

Triggers:

• User has .ips or .crash file to analyze

• User pasted crash report text

• Need to parse crash log programmatically

• Identify crash pattern from exception type

• Check symbolication status

Why crash-analyzer: Autonomous agent that parses crash reports, identifies patterns (null pointer, Swift runtime, watchdog, jetsam), and generates actionable analysis.

Invoke: Launch crash-analyzer agent or /axiom:analyze-crash

12. MetricKit API Reference → metrickit-ref

Triggers:

• MetricKit setup and subscription

• MXMetricPayload parsing (CPU, memory, launches, hitches)

• MXDiagnosticPayload parsing (crashes, hangs, disk writes)

• MXCallStackTree decoding and symbolication

• Field crash/hang collection

• Background exit metrics

Why metrickit-ref: Complete MetricKit API reference with setup patterns, payload parsing, and integration with crash reporting systems.

Invoke: /skill axiom-metrickit-ref

13. Hang Diagnostics → hang-diagnostics

Triggers:

• App hangs or freezes

• Main thread blocked for >1 second

• UI unresponsive to touches

• Xcode Organizer shows hang diagnostics

• MXHangDiagnostic from MetricKit

• Watchdog terminations (app killed during launch/background transition)

Why hang-diagnostics: Systematic diagnosis of hangs with decision tree for busy vs blocked main thread, tool selection (Time Profiler, System Trace), and 8 common hang patterns with fixes.

Invoke: /skill axiom-hang-diagnostics

14. Live Debugging → axiom-lldb

Triggers:

• Need to reproduce a crash interactively

• Want to set breakpoints and inspect state

• Crash report analyzed, now need live investigation

• Need to attach debugger to running app

Why axiom-lldb: Crash reports tell you WHAT crashed. LLDB tells you WHY.

Invoke: /skill axiom-lldb

16. Runtime Console Capture → xclog-ref

Triggers:

• Need to see what the app is logging at runtime

• App crashes but no crash report (need console output)

• Silent failures (network, data, auth) with no UI feedback

• Want to capture print()/os_log() output from simulator

• Need structured log output for analysis

• "What is the app printing?"

Why xclog-ref: Xcode's debug console isn't accessible externally. xclog combines simctl stdout/stderr with log stream JSON to capture everything print(), NSLog(), os_log(), and Logger emit — with structured fields (level, subsystem, category) for automated analysis.

Invoke: /skill axiom-xclog-ref or /axiom:console

15. Code Signing Issues → code-signing

Triggers:

• "No signing certificate found"

• "Provisioning profile doesn't include signing certificate"

• errSecInternalComponent in CI

• ITMS-90035 Invalid Signature on upload

• Ambiguous identity / multiple certificates

• Entitlement mismatch or missing capability

• Setting up CI/CD code signing (GitHub Actions, fastlane match)

• Certificate expired or revoked

Why code-signing: Code signing errors are NEVER code bugs — they are 100% configuration (certificates, profiles, entitlements, keychains). Diagnosing with CLI tools takes 5 minutes vs hours of guessing.

Invoke: /skill axiom-code-signing (workflows) or /skill axiom-code-signing-diag (troubleshooting)

Decision Tree

• Mysterious/intermittent/clean build fails? → xcode-debugging (environment-first)

• SPM dependency conflict? → spm-conflict-resolver (Agent)

• CocoaPods/other dependency conflict? → build-debugging

• Slow build time? → build-performance

• Security/privacy/App Store prep? → security-privacy-scanner (Agent)

• Want automated build fix (environment-first diagnostics)? → build-fixer (Agent)

• Want build time optimization scan? → build-optimizer (Agent)

• Modernization/deprecated APIs? → modernization-helper (Agent)

• TestFlight crash/feedback? → testflight-triage

• Navigating App Store Connect? → app-store-connect-ref

• Have a crash log (.ips/.crash)? → crash-analyzer (Agent)

• MetricKit setup/parsing? → metrickit-ref

• App hang/freeze/watchdog? → hang-diagnostics

• Need to reproduce crash interactively / inspect runtime state? → axiom-lldb

• Code signing error (certificate, profile, entitlement, Keychain)? → code-signing / code-signing-diag

• Need to see runtime console output (print/os_log)? → xclog-ref or /axiom:console

Anti-Rationalization

Thought Reality

"I know how to fix this linker error" Linker errors have 4+ root causes. xcode-debugging diagnoses all in 2 min.

"Let me just clean the build folder" Clean builds mask the real issue. xcode-debugging finds the root cause.

"It's just an SPM issue, I'll fix Package.swift" SPM conflicts cascade. spm-conflict-resolver analyzes the full dependency graph.

"The simulator is just slow today" Simulator issues indicate environment corruption. xcode-debugging checks systematically.

"I'll skip environment checks, it compiles locally" Environment-first saves 30+ min. Every time.

"I'll read the crash report more carefully instead of reproducing" Crash reports show WHAT crashed, not WHY. Reproducing in LLDB with breakpoints reveals the actual state. axiom-lldb has the workflow.

"I know my certificate is fine, let me check the code" Code signing errors are NEVER code bugs. 100% configuration. code-signing diagnoses with CLI in 5 min.

"I can't see what the app is logging without Xcode" xclog captures print() + os_log from the simulator. Structured JSON output with level, subsystem, category. /axiom:console or /skill axiom-xclog-ref .

When NOT to Use (Conflict Resolution)

Do NOT use ios-build for these — use the correct router instead:

Error Type Correct Router Why NOT ios-build

Swift 6 concurrency errors ios-concurrency Code error, not environment

SwiftData migration errors ios-data Schema issue, not build environment

"Sending 'self' risks data race" ios-concurrency Language error, not Xcode issue

Type mismatch / compilation errors Fix the code These are code bugs

ios-build is for environment mysteries, not code errors:

• ✅ "No such module" when code is correct

• ✅ Simulator won't boot

• ✅ Clean build fails, incremental works

• ✅ Zombie xcodebuild processes

• ❌ Swift concurrency warnings/errors

• ❌ Database migration failures

• ❌ Type checking errors in valid code

Example Invocations

User: "My build failed with a linker error" → Invoke: /skill axiom-xcode-debugging (environment-first diagnostic)

User: "Builds are taking 10 minutes" → Invoke: /skill axiom-build-performance

User: "SPM won't resolve dependencies" → Invoke: spm-conflict-resolver agent

User: "Two packages require different versions of the same dependency" → Invoke: spm-conflict-resolver agent

User: "Duplicate symbol linker error" → Invoke: spm-conflict-resolver agent

User: "I need to prepare for App Store security review" → Invoke: security-privacy-scanner agent

User: "Do I need a Privacy Manifest?" → Invoke: security-privacy-scanner agent

User: "Are there hardcoded credentials in my code?" → Invoke: security-privacy-scanner agent

User: "How do I migrate from ObservableObject to @Observable?" → Invoke: modernization-helper agent

User: "Update my code to use modern SwiftUI patterns" → Invoke: modernization-helper agent

User: "Should I still use @StateObject?" → Invoke: modernization-helper agent

User: "A beta tester said my app crashed" → Invoke: /skill axiom-testflight-triage

User: "I see crashes in App Store Connect but don't know how to investigate" → Invoke: /skill axiom-testflight-triage

User: "My crash logs aren't symbolicated" → Invoke: /skill axiom-testflight-triage

User: "I need to review TestFlight feedback" → Invoke: /skill axiom-testflight-triage

User: "How do I find crashes in App Store Connect?" → Invoke: /skill axiom-app-store-connect-ref

User: "Where's the crash-free users metric in ASC?" → Invoke: /skill axiom-app-store-connect-ref

User: "How do I export crash data from App Store Connect?" → Invoke: /skill axiom-app-store-connect-ref

User: "Analyze this crash log" [pastes .ips content] → Invoke: crash-analyzer agent or /axiom:analyze-crash

User: "Parse this .ips file: ~/Library/Logs/DiagnosticReports/MyApp.ips" → Invoke: crash-analyzer agent or /axiom:analyze-crash

User: "Why did my app crash? Here's the report..." → Invoke: crash-analyzer agent or /axiom:analyze-crash

User: "How do I set up MetricKit to collect crash data?" → Invoke: /skill axiom-metrickit-ref

User: "How do I parse MXDiagnosticPayload?" → Invoke: /skill axiom-metrickit-ref

User: "What's in MXCallStackTree and how do I decode it?" → Invoke: /skill axiom-metrickit-ref

User: "My app hangs sometimes" → Invoke: /skill axiom-hang-diagnostics

User: "The main thread is blocked and UI is unresponsive" → Invoke: /skill axiom-hang-diagnostics

User: "Xcode Organizer shows hang diagnostics for my app" → Invoke: /skill axiom-hang-diagnostics

User: "My app was killed by watchdog during launch" → Invoke: /skill axiom-hang-diagnostics

User: "I have a crash report and need to reproduce it in the debugger" → Invoke: /skill axiom-lldb

User: "How do I set breakpoints to catch this crash?" → Invoke: /skill axiom-lldb

User: "My build is failing with BUILD FAILED but no error details" → Invoke: build-fixer agent or /axiom:fix-build

User: "Build sometimes succeeds, sometimes fails" → Invoke: build-fixer agent or /axiom:fix-build

User: "How can I speed up my Xcode build times?" → Invoke: build-optimizer agent or /axiom:optimize-build

User: "No signing certificate found when I try to build" → Invoke: /skill axiom-code-signing-diag

User: "errSecInternalComponent in my GitHub Actions CI" → Invoke: /skill axiom-code-signing-diag

User: "How do I set up code signing for GitHub Actions?" → Invoke: /skill axiom-code-signing

User: "What is my app printing to the console?" → Invoke: /skill axiom-xclog-ref or /axiom:console

User: "I need to see the simulator console output" → Invoke: /skill axiom-xclog-ref or /axiom:console

User: "The app fails silently, no error in the UI" → Invoke: /skill axiom-xclog-ref or /axiom:console