playbooks

home / skills / willsigmon / sigstack / ios-build-expert

ios-build-expert skill

/plugins/ios-dev/skills/ios-build-expert

This skill helps iOS developers diagnose and fix Xcode build, simulator, and workflow issues with structured diagnostics and quick, reliable fixes.

npx playbooks add skill willsigmon/sigstack --skill ios-build-expert

Review the files below or copy the command above to add this skill to your agents.

Files (1)
SKILL.md
1.3 KB
---
name: iOS Build Expert
description: iOS/Xcode build issues - compilation errors, simulator problems, build analysis, diagnostics, quick fixes
allowed-tools: Bash, Read, Edit, Grep
model: sonnet
---

# iOS Build Expert

Complete iOS build system expertise for Leavn app.

## Quick Commands
```bash
make clean          # Clean build
make sim-build      # Build for simulator
make test           # Run tests
xcrun simctl list   # List simulators
```

## Build Error Workflow
1. Run build, capture output: `make sim-build 2>&1 | tee /tmp/build.log`
2. Categorize errors: type errors, missing imports, actor isolation, etc.
3. Fix in dependency order (imports → types → logic)
4. Rebuild and verify

## Simulator Issues
- **Reset**: `xcrun simctl erase all`
- **Boot specific**: `xcrun simctl boot "iPhone 15 Pro"`
- **Install app**: `xcrun simctl install booted path/to/app`
- **Launch**: `xcrun simctl launch booted bundle.id`

## Common Fixes
- Missing module: Check Package.swift dependencies
- Actor isolation: Add @MainActor or nonisolated
- Type mismatch: Check @Observable vs @Published patterns
- Build settings: Verify project.yml / xcodegen

## Visual Debugging
- Screenshot: `xcrun simctl io booted screenshot /tmp/screen.png`
- Record: `xcrun simctl io booted recordVideo /tmp/video.mov`

Use when: Build failures, simulator issues, Xcode errors, diagnostics

Overview

This skill provides hands-on expertise for diagnosing and fixing iOS and Xcode build problems for Swift projects. It focuses on rapid triage of compilation errors, simulator problems, dependency issues, and build setting mismatches. The goal is to get a reproducible local build quickly and outline minimal, safe fixes to restore CI and developer productivity.

How this skill works

I inspect build output, classify errors by root cause (dependency, type, actor isolation, missing import, build setting), and apply fixes in dependency order to avoid cascading failures. I use simulator and CLI tools to reproduce runtime issues, capture screenshots or video, and verify installations and launches. The workflow emphasizes capturing logs, iterative rebuilds, and minimal changes to restore a green build.

When to use it

  • Compilation errors after pull or dependency updates
  • Simulator won’t boot, app won’t install, or launch failures
  • Strange runtime crashes that differ between device and simulator
  • CI build failures related to Xcode settings or package resolution
  • After merging large refactors that introduce type or actor errors

Best practices

  • Capture full build logs (e.g., tee /tmp/build.log) before editing for accurate triage
  • Fix issues from the bottom of the dependency graph up: imports → types → logic
  • Prefer small, isolated changes and rebuild frequently to narrow causes
  • Use simulator CLI to reproduce issues and gather screenshots or recordings
  • Verify Package.swift and XcodeGen/project.yml settings when modules are missing

Example use cases

  • Resolve missing module errors by inspecting Package.swift and Xcode build settings
  • Add @MainActor or nonisolated annotations to address actor isolation compiler errors
  • Fix type mismatches by auditing @Observable vs @Published usage and correcting models
  • Reset and boot specific simulators, install the app, and reproduce UI issues with screenshots or video
  • Run a local test suite after fixes to confirm behavior before pushing to CI

FAQ

What immediate evidence should I gather when a build fails?

Save the full build log, note the Xcode and Swift toolchain versions, and capture any failing file paths and first error lines before making changes.

How do I handle a simulator that refuses to boot or install the app?

Erase all simulators to clear state, boot the target device, then use simctl install and launch; capture screenshots or video to document behavior.