build-debug-ios

name	build-debug-ios
description	Build, launch, and debug iOS simulator apps: run the target command, capture logs, capture screenshots, dump accessibility state, and summarize UI or runtime regressions.

Build Debug (iOS)

Overview

Use this skill to create deterministic artifacts for iOS simulator app debugging without hardcoding any one repo, build system, or app name. Configure the run command and app identifiers for the current project, then use the helper script to capture logs, screenshots, and optional accessibility output.

Prepare the Session

Before running anything, determine:

1. A one-shot RUN_CMD that builds and launches the app without opening an interactive watcher.
2. APP_PROCESS — the process name used to derive the default log predicate.
3. Optionally, SIMULATOR_UDID or SIMULATOR_FILTER.

Prefer a command that exits after launch. If the normal workflow uses a long-running watcher, derive a non-interactive build-and-launch command for artifact capture.

Workflow

Run the iOS helper against the project root:

RUN_CMD='xcodebuild -scheme Example -destination "platform=iOS Simulator,name=iPhone 16" build && xcrun simctl launch booted com.example.app' \
APP_PROCESS='Example' \
${CLAUDE_SKILL_DIR}/scripts/capture_ios_debug.sh /path/to/repo

Environment variables:

• RUN_CMD (required): Build/install/launch command executed with bash -lc.
• APP_PROCESS (optional): Process name used to derive the default log predicate.
• LOG_PREDICATE (optional): Custom log stream predicate. Overrides APP_PROCESS.
• SIMULATOR_UDID (optional): Exact simulator to boot and use.
• SIMULATOR_FILTER (optional): Device-name substring for auto-selection. Defaults to iPhone.
• WAIT_FOR_SECONDS (optional): Time to allow the app to settle before screenshotting. Defaults to 5.
• OUT_DIR (optional): Artifact directory. Defaults to /tmp/apple-ios-debug.

The script prints:

• UDID
• RUN_STATUS
• RUN_EXIT_CODE
• RUN_LOG
• LOG_FILE
• SCREENSHOT
• UI_DUMP

If axe is installed, inspect or interact with the simulator UI:

axe describe-ui --udid "$UDID"
axe tap --udid "$UDID" --id action.primary

If axe is unavailable, install it with brew install cameroncooke/axe/axe, or rely on the screenshot and log output.

Reporting

Always return:

1. Build/run status, including whether RUN_CMD exited, failed, or was still running during capture.
2. Artifact paths.
3. UI verdict: expected or unexpected.
4. Specific mismatch list tied to screenshots, accessibility output, or logs.
5. Missing prerequisites or gaps such as no axe, no Accessibility permission, or screenshot capture failure.