Xcode Build Fixer

Xcode Build Fixer

Use this skill to implement approved build optimization changes and verify them with a benchmark.

Core Rules

• Only apply changes that have explicit developer approval.
• Apply one logical fix at a time so changes are reviewable and reversible.
• Re-benchmark after applying changes to verify improvement.
• Report exactly what changed, which files were touched, and the measured delta.
• If a change produces no improvement or causes a regression, flag it immediately.

Inputs

The fixer expects one of:

• An approved optimization plan at .build-benchmark/optimization-plan.md with checked approval boxes.
• An explicit developer instruction describing the fix to apply (e.g., "set DEBUG_INFORMATION_FORMAT to dwarf for Debug").

When working from an optimization plan, read the approval checklist and implement only the checked items.

Fix Categories

Build Settings

Change project.pbxproj values to match the recommendations in build-settings-best-practices.md.

Typical fixes:

• Set DEBUG_INFORMATION_FORMAT = dwarf for Debug
• Set SWIFT_COMPILATION_MODE = singlefile for Debug
• Enable COMPILATION_CACHE_ENABLE_CACHING = YES
• Enable EAGER_LINKING = YES for Debug
• Align cross-target settings to eliminate module variants

When editing project.pbxproj, locate the correct buildSettings block by matching the target name and configuration name. Verify the change with xcodebuild -showBuildSettings after applying.

Script Phases

Fix run script phases that waste time during incremental or debug builds.

Typical fixes:

• Add input and output file declarations so Xcode can skip unchanged scripts.
• Add configuration guards: [[ "$CONFIGURATION" != "Release" ]] && exit 0 for release-only scripts.
• Move input/output lists into .xcfilelist files when the list is long.
• Enable Based on dependency analysis when inputs and outputs are declared.

Source-Level Compilation Fixes

Apply code changes that reduce type-checker and compiler overhead. See references/fix-patterns.md for before/after patterns.

Typical fixes:

• Add explicit type annotations to complex expressions.
• Break long chained or nested expressions into intermediate typed variables.
• Mark classes final when they are not subclassed.
• Tighten access control (private/fileprivate) for internal-only symbols.
• Extract monolithic SwiftUI body properties into smaller composed subviews.
• Replace deeply nested result-builder code with separate typed helpers.
• Add explicit return types to closures passed to generic functions.

SPM Restructuring

Restructure Swift packages to improve build parallelism and reduce rebuild scope.

Typical fixes:

• Move shared types to a lower-layer module to eliminate circular or upward dependencies.
• Split oversized modules (200+ files) by feature area.
• Extract protocol definitions into lightweight interface modules.
• Remove unnecessary @_exported import usage.
• Align build options across targets that import the same packages to prevent module variant duplication.
• Pin branch-tracked dependencies to tagged versions or commit hashes for deterministic resolution.

Before applying version pin changes:

• Run git ls-remote --tags <url> to confirm tags exist. If the upstream has no tags, pin to a specific revision hash instead.
• Verify the pinned version resolves successfully with xcodebuild -resolvePackageDependencies before proceeding.

Execution Workflow

1. Read the approved optimization plan or developer instruction.
2. For each approved item, identify the exact files and locations to change.
3. Apply the change.
4. Verify the change compiles: run a quick xcodebuild build to confirm no errors were introduced.
5. After all approved changes are applied, re-benchmark using the same inputs from the original baseline:

   python3 scripts/benchmark_builds.py \
     --project App.xcodeproj \
     --scheme MyApp \
     --configuration Debug \
     --destination "platform=iOS Simulator,name=iPhone 16" \
     --output-dir .build-benchmark

6. Compare post-change medians to the baseline and report deltas.

Evaluating Regressions

Not every slower number is a true regression. The fixer must evaluate the full picture before recommending a revert.

Compilation caching trade-off

A change like COMPILATION_CACHE_ENABLE_CACHING = YES may make a standard clean build slightly slower (cache population overhead) while making cached clean builds significantly faster. Since cached clean builds reflect the realistic developer workflow (branch switching, pulling changes, Clean Build Folder with a warm cache), a slower standard clean build paired with a faster cached clean build is a net improvement, not a regression. The same logic applies to any change where the first-time cost is higher but subsequent builds benefit.

Compare all build types

Evaluate standard clean, cached clean (when available), and incremental builds together. A change is only a clear regression if it makes the metrics that matter to the developer's daily workflow worse. If only the cold-start clean build is slower but the developer rarely does truly cold builds, that may be acceptable.

Per-change vs. cumulative

A single change that regresses on its own may still be worth keeping if it enables a larger cumulative improvement (e.g., enabling compilation caching makes one build type slower but unlocks cache benefits for everything else).

Best-practice settings are not revert candidates

Some build settings are Apple's recommended modern defaults. These should be applied and kept regardless of whether the immediate benchmark shows a measurable improvement. They are not speculative optimizations -- they align the project with Apple's toolchain direction and will compound in value over future Xcode releases. The fixer must never recommend reverting these settings based on a single benchmark result.

Best-practice settings that should always be kept once applied:

• COMPILATION_CACHE_ENABLE_CACHING = YES -- Apple is actively investing in this; the cache improves with each Xcode release and compounds across real workflows
• EAGER_LINKING = YES (Debug) -- allows the linker to overlap with compilation
• SWIFT_USE_INTEGRATED_DRIVER = YES -- eliminates inter-process scheduling overhead
• DEBUG_INFORMATION_FORMAT = dwarf (Debug) -- avoids unnecessary dSYM generation
• SWIFT_COMPILATION_MODE = singlefile (Debug) -- incremental recompilation
• ONLY_ACTIVE_ARCH = YES (Debug) -- no reason to build all architectures locally

When reporting on these settings, use language like: "Applied recommended build setting. No immediate benchmark improvement measured, but this aligns with Apple's recommended configuration and positions the project for future Xcode improvements."