axiom-build

What this skill does

# Build & Environment

**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**: `skills/xcode-debugging.md`

---

### 2. Slow Builds → **build-performance**
**Triggers**:
- Compilation takes too long
- Type checking bottlenecks
- Want to optimize build time
- Build Timeline shows slow phases

**Invoke**: `skills/build-performance.md`

---

### 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**: `skills/build-debugging.md`

---

### 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**: See axiom-shipping (skills/testflight-triage.md)

---

### 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**: See axiom-shipping (skills/app-store-connect-ref.md)

---

### 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**: See axiom-performance (`skills/metrickit-ref.md`)

---

### 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**: See axiom-performance (`skills/hang-diagnostics.md`)

---

### 14. Live Debugging → **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 lldb**: Crash reports tell you WHAT crashed. LLDB tells you WHY.

**Invoke**: `skills/lldb.md`

---

### 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**: `/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 co