xcode-compilation-analyzer

SKILL.md

Xcode Compilation Analyzer

Use this skill when compile time, not just general project configuration, looks like the bottleneck.

Core Rules

Start from evidence, ideally a recent .build-benchmark/ artifact or raw timing-summary output.

Prefer analysis-only compiler flags over persistent project edits during investigation.

Rank findings by expected wall-clock impact, not cumulative compile-time impact. When compile tasks are heavily parallelized (sum of compile categories >> wall-clock median), note that fixing individual hotspots may improve parallel efficiency without reducing build wait time.

When the evidence points to parallelized work rather than serial bottlenecks, label recommendations as "Reduces compiler workload (parallel)" rather than "Reduces build time."

Do not edit source or build settings without explicit developer approval.

What To Inspect

Build Timing Summary output from clean and incremental builds

long-running CompileSwiftSources or per-file compilation tasks

SwiftEmitModule time -- can reach 60s+ after a single-line change in large modules; if it dominates incremental builds, the module is likely too large or macro-heavy

Planning Swift module time -- if this category is disproportionately large in incremental builds (up to 30s per module), it signals unexpected input invalidation or macro-related rebuild cascading

ad hoc runs with:

-Xfrontend -warn-long-expression-type-checking=<ms>

-Xfrontend -warn-long-function-bodies=<ms>

deeper diagnostic flags for thorough investigation:

-Xfrontend -debug-time-compilation -- per-file compile times to rank the slowest files

-Xfrontend -debug-time-function-bodies -- per-function compile times (unfiltered, complements the threshold-based warning flags)

-Xswiftc -driver-time-compilation -- driver-level timing to isolate driver overhead

-Xfrontend -stats-output-dir <path> -- detailed compiler statistics (JSON) per compilation unit for root-cause analysis

mixed Swift and Objective-C surfaces that increase bridging work

Analysis Workflow

Identify whether the main issue is broad compilation volume or a few extreme hotspots.

Parse timing-summary categories and rank the biggest compile contributors.

Run the diagnostics script to surface type-checking hotspots:
python3 scripts/diagnose_compilation.py \
  --project App.xcodeproj \
  --scheme MyApp \
  --configuration Debug \
  --destination "platform=iOS Simulator,name=iPhone 16" \
  --threshold 100 \
  --output-dir .build-benchmark

This produces a ranked list of functions and expressions that exceed the millisecond threshold. Use the diagnostics artifact alongside source inspection to focus on the most expensive files first.

Map the evidence to a concrete recommendation list.

Separate code-level suggestions from project-level or module-level suggestions.

Apple-Derived Checks

Look for these patterns first:

missing explicit type information in expensive expressions

complex chained or nested expressions that are hard to type-check

delegate properties typed as AnyObject instead of a concrete protocol

oversized Objective-C bridging headers or generated Swift-to-Objective-C surfaces

header imports that skip framework qualification and miss module-cache reuse

classes missing final that are never subclassed

overly broad access control (public/open) on internal-only symbols

monolithic SwiftUI body properties that should be decomposed into subviews

long method chains or closures without intermediate type annotations

Reporting Format

For each recommendation, include:

observed evidence

likely affected file or module

expected wait-time impact (e.g. "Expected to reduce your clean build by ~2s" or "Reduces parallel compile work but unlikely to reduce build wait time")

confidence

whether approval is required before applying it

If the evidence points to project configuration instead of source, hand off to xcode-project-analyzer by reading its SKILL.md and applying its workflow to the same project context.

Preferred Tactics

Suggest ad hoc flag injection through the build command before recommending persistent build-setting changes.

Prefer narrowing giant view builders, closures, or result-builder expressions into smaller typed units.

Recommend explicit imports and protocol typing when they reduce compiler search space.

Call out when mixed-language boundaries are the real issue rather than Swift syntax alone.

Additional Resources

For the detailed audit checklist, see references/code-compilation-checks.md

For the shared recommendation structure, see references/recommendation-format.md

For source citations, see references/build-optimization-sources.md