You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
CocoaPods is deprecated. When a project uses CocoaPods, do not attempt CocoaPods-specific build optimizations (linkage mode changes, `COCOAPODS_PARALLEL_CODE_SIGN`, Podfile tweaks). These are unreliable and frequently regress build times.
51
+
52
+
Recommend migrating to Swift Package Manager as the highest-impact long-term improvement. SPM advantages for build time: compilation caching works out of the box, better build parallelism from the dependency graph, no `pod install` xcconfig regeneration overhead, and native Xcode integration with full support for modern features like explicit modules.
53
+
54
+
Focus analysis on first-party targets and build settings the project controls directly. Do not audit `Pods.xcodeproj` or the Podfile.
55
+
48
56
## Script Phase Analysis
49
57
50
58
The `xcode-project-analyzer` inspects every Run Script phase in the project for missing metadata and unnecessary execution.
@@ -97,7 +105,7 @@ Even with no source edits, incremental builds incur fixed overhead. The agent me
97
105
|`CopySwiftLibs`| Copies Swift standard libraries | Runs even when nothing changed |
98
106
|`RegisterWithLaunchServices`| Registers the built app | Fast but always present |
99
107
|`ProcessInfoPlistFile`| Re-processes Info.plist files | Scales with target count |
100
-
|`ExtractAppIntentsMetadata`| Extracts App Intents metadata | Unnecessary overhead if the project does not use App Intents |
108
+
|`ExtractAppIntentsMetadata`| Extracts App Intents metadata from all targets including third-party dependencies | Driven by Xcode, not by per-target project settings; unnecessary overhead if the project does not use App Intents but not cleanly suppressible from the repo (classify as `xcode-behavior`)|
101
109
102
110
A zero-change build above 5 seconds on Apple Silicon typically indicates script phase overhead or excessive codesigning.
Copy file name to clipboardExpand all lines: references/recommendation-format.md
+17-5Lines changed: 17 additions & 5 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -8,13 +8,23 @@ Each recommendation should include:
8
8
9
9
-`title`
10
10
-`wait_time_impact` -- plain-language statement of expected wall-clock impact, e.g. "Expected to reduce your clean build by ~3s", "Reduces parallel compile work but unlikely to reduce build wait time", or "Impact on wait time is uncertain -- re-benchmark to confirm"
11
+
-`actionability` -- classifies how fixable the issue is from the project (see values below)
11
12
-`category`
12
13
-`observed_evidence`
13
14
-`estimated_impact`
14
15
-`confidence`
15
16
-`approval_required`
16
17
-`benchmark_verification_status`
17
18
19
+
### Actionability Values
20
+
21
+
Every recommendation must include an `actionability` classification:
22
+
23
+
-`repo-local` -- Fix lives entirely in project files, source code, or local configuration. The developer can apply it without side effects outside the repo.
24
+
-`package-manager` -- Requires CocoaPods or SPM configuration changes that may have broad side effects (e.g., linkage mode, dependency restructuring). These should be benchmarked before and after.
25
+
-`xcode-behavior` -- Observed cost is driven by Xcode internals and is not suppressible from the project. Report the finding for awareness but do not promise a fix.
26
+
-`upstream` -- Requires changes in a third-party dependency or external tool. The developer cannot fix it locally.
27
+
18
28
## Suggested Optional Fields
19
29
20
30
-`scope`
@@ -32,6 +42,7 @@ Each recommendation should include:
32
42
{
33
43
"title": "Guard a release-only symbol upload script",
34
44
"wait_time_impact": "Expected to reduce your incremental build by approximately 6 seconds.",
45
+
"actionability": "repo-local",
35
46
"category": "project",
36
47
"observed_evidence": [
37
48
"Incremental builds spend 6.3 seconds in a run script phase.",
@@ -54,11 +65,12 @@ When rendering for human review, preserve the same field order:
54
65
55
66
1. title
56
67
2. wait-time impact
57
-
3. observed evidence
58
-
4. estimated impact
59
-
5. confidence
60
-
6. approval required
61
-
7. benchmark verification status
68
+
3. actionability
69
+
4. observed evidence
70
+
5. estimated impact
71
+
6. confidence
72
+
7. approval required
73
+
8. benchmark verification status
62
74
63
75
That makes it easier for the developer to approve or reject specific items quickly.
Copy file name to clipboardExpand all lines: skills/xcode-build-fixer/SKILL.md
+79Lines changed: 79 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -100,6 +100,46 @@ Before applying version pin changes:
100
100
```
101
101
6. Compare post-change medians to the baseline and report deltas.
102
102
103
+
## Evaluating Regressions
104
+
105
+
Not every slower number is a true regression. The fixer must evaluate the full picture before recommending a revert.
106
+
107
+
### Compilation caching trade-off
108
+
109
+
A change like `COMPILATION_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.
110
+
111
+
### Compare all build types
112
+
113
+
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.
114
+
115
+
### Per-change vs. cumulative
116
+
117
+
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).
118
+
119
+
### Best-practice settings are not revert candidates
120
+
121
+
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.
122
+
123
+
Best-practice settings that should always be kept once applied:
124
+
125
+
-`COMPILATION_CACHING = YES` -- Apple is actively investing in this; the cache improves with each Xcode release and compounds across real workflows
126
+
-`EAGER_LINKING = YES` (Debug) -- allows the linker to overlap with compilation
-`ONLY_ACTIVE_ARCH = YES` (Debug) -- no reason to build all architectures locally
131
+
132
+
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."
133
+
134
+
### When to recommend revert (speculative changes only)
135
+
136
+
For changes that are not best-practice settings (e.g., source refactors, linkage experiments, script phase modifications, dependency restructuring):
137
+
138
+
- If the cumulative pass shows wall-clock regression across all measured build types (standard clean, cached clean, and incremental are all slower), recommend reverting all speculative changes unless the developer explicitly asks to keep specific items for non-performance reasons.
139
+
- For each individual speculative change: if it shows no median improvement and no cached/incremental benefit either, flag it with `Recommend revert` and the measured delta.
140
+
- Distinguish between "outlier reduction only" (improved worst-case but not median) and "median improvement" (improved typical developer wait).
141
+
- When a change trades off one build type for another (e.g., slower standard clean but faster cached clean), present both numbers clearly and let the developer decide. Frame it as: "Standard clean builds are X.Xs slower, but cached clean builds (the realistic daily workflow) are Y.Ys faster."
142
+
103
143
## Reporting
104
144
105
145
Lead with the wall-clock result in plain language:
@@ -124,6 +164,45 @@ For changes valuable for non-benchmark reasons (deterministic package resolution
124
164
125
165
Note: `COMPILATION_CACHING` has been measured at 5-14% faster clean builds across tested projects (87 to 1,991 Swift files). The benefit compounds in real developer workflows where the cache persists between builds -- branch switching, pulling changes, and CI with persistent DerivedData. The benchmark script auto-detects this setting and runs a cached clean phase for validation.
126
166
167
+
## Execution Report
168
+
169
+
After the optimization pass is complete, produce a structured execution report. This gives the developer a clear summary of what was attempted, what worked, and what the final state is.
170
+
171
+
Structure:
172
+
173
+
```markdown
174
+
## Execution Report
175
+
176
+
### Baseline
177
+
- Clean build median: X.Xs
178
+
- Cached clean build median: X.Xs (if applicable)
179
+
- Incremental build median: X.Xs
180
+
181
+
### Changes Applied
182
+
183
+
| # | Change | Actionability | Measured Result | Status |
- Finding: reason it could not be addressed from the repo
196
+
```
197
+
198
+
Status values:
199
+
200
+
-`Kept` -- Change improved or maintained build times and was kept.
201
+
-`Kept (best practice)` -- Change is a recommended build setting; kept regardless of immediate benchmark result.
202
+
-`Reverted` -- Change regressed build times and was reverted.
203
+
-`Blocked` -- Change could not be applied due to project structure, Xcode behavior, or external constraints.
204
+
-`No improvement` -- Change compiled but showed no measurable wall-time benefit. Include whether it was kept (for non-performance reasons) or reverted.
205
+
127
206
## Escalation
128
207
129
208
If during implementation you discover issues outside this skill's scope:
Copy file name to clipboardExpand all lines: skills/xcode-build-orchestrator/SKILL.md
+2-1Lines changed: 2 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -27,6 +27,7 @@ Run this phase in agent mode because the agent needs to execute builds, run benc
27
27
1. Collect the build target context: workspace or project, scheme, configuration, destination, and current pain point. When both `.xcworkspace` and `.xcodeproj` exist, prefer `.xcodeproj` unless the workspace contains sub-projects required for the build. Workspaces that reference external projects may fail if those projects are not checked out.
28
28
2. Run `xcode-build-benchmark` to establish a baseline if no fresh benchmark exists. The benchmark script auto-detects `COMPILATION_CACHING = YES` and includes cached clean builds that measure the realistic developer experience (warm cache). If the build fails to compile, check `git log` for a recent buildable commit. When working in a worktree, cherry-picking a targeted build fix from a feature branch is acceptable to reach a buildable state. If SPM packages reference gitignored directories in their `exclude:` paths (e.g., `__Snapshots__`), create those directories before building -- worktrees do not contain gitignored content and `xcodebuild -resolvePackageDependencies` will crash otherwise.
29
29
3. Verify the benchmark artifact has non-empty `timing_summary_categories`. If empty, the timing summary parser may have failed -- re-parse the raw logs or inspect them manually. If `COMPILATION_CACHING` is enabled, also verify the artifact includes `cached_clean` runs.
30
+
-**Benchmark confidence check**: For each build type (clean, cached clean, incremental), compare the min and max values. If the spread (max - min) exceeds 20% of the median, flag the benchmark as having high variance and recommend running additional repetitions (5+ runs) before drawing conclusions. High variance makes it difficult to distinguish real improvements from noise. After applying changes, only claim an improvement if the post-change median falls outside the baseline's min-max range.
30
31
4. If incremental builds are the primary pain point and Xcode 16.4+ is available, recommend the developer enable **Task Backtraces** (Scheme Editor > Build tab > Build Debugging > "Task Backtraces"). This reveals why each task re-ran, which is critical for diagnosing unexpected replanning or input invalidation. Include any Task Backtrace evidence in the analysis.
31
32
5. Determine whether compile tasks are likely blocking wall-clock progress or just consuming parallel CPU time. Compare the sum of all timing-summary category seconds against the wall-clock median: if the sum is 2x+ the median, most work is parallelized and compile hotspot fixes are unlikely to reduce wait time. If `SwiftCompile`, `CompileC`, `SwiftEmitModule`, or `Planning Swift module` dominate the timing summary **and** appear likely to be on the critical path, run `diagnose_compilation.py` to capture type-checking hotspots. If they are parallelized, still run diagnostics but label findings as "parallel efficiency improvements" rather than "build time improvements."
32
33
6. Run the specialist analyses that fit the evidence by reading each skill's SKILL.md and applying its workflow:
@@ -104,7 +105,7 @@ Lead with the wall-clock result in plain language, e.g.: "Your clean build now t
104
105
- absolute and percentage wall-clock deltas
105
106
- what changed
106
107
- what was intentionally left unchanged
107
-
- confidence notes if noise prevents a strong conclusion
108
+
- confidence notes if noise prevents a strong conclusion -- if benchmark variance is high (min-to-max spread exceeds 20% of median), say so explicitly rather than presenting noisy numbers as definitive improvements or regressions
108
109
- if cumulative task metrics improved but wall-clock did not, say plainly: "Compiler workload decreased but build wait time did not improve. This is expected when Xcode runs these tasks in parallel with other equally long work."
109
110
- a ready-to-paste community results row and a link to open a PR (see the report template)
- If cumulative task metrics improved but wall-clock did not: "Compiler workload decreased but build wait time did not improve. This is expected when Xcode runs these tasks in parallel with other equally long work."
99
115
- If standard clean builds are slower but cached clean builds are faster: "Standard clean builds show overhead from compilation cache population. Cached clean builds (the realistic developer workflow) are faster, confirming the net benefit."
100
116
117
+
### Blocked or Non-Actionable Findings
118
+
- Finding: reason it could not be addressed from the repo
0 commit comments