skills/avdlee__xcode-build-optimization-agent-skill

mirror of https://github.com/AvdLee/Xcode-Build-Optimization-Agent-Skill.git synced 2026-09-14 13:59:59 +08:00

Files

T

Antoine van der Lee a28f3bc503 Incorporate learnings from Daily macOS (ObjC + CocoaPods) test case

A community member ran the optimization skills on an older ObjC + CocoaPods
project. The agent improvised CocoaPods-specific changes not covered by any
reference material, overestimated how actionable some findings were, and
produced a 14% regression. This commit addresses the root causes:

- Add actionability classification (repo-local / package-manager /
  xcode-behavior / upstream) to the recommendation format so every finding
  states how fixable it is from the repo
- Add CocoaPods deprecation notice: do not attempt CocoaPods-specific
  optimizations; recommend migrating to SPM instead
- Add regression-aware revert guidance: best-practice settings are never
  revert candidates; speculative changes are only reverted when all build
  types regress; compilation caching trade-offs are evaluated holistically
- Add structured execution report to the fixer and orchestrator template
  so each change is tracked with its measured result and kept/reverted status
- Add benchmark confidence checks: flag high-variance runs and recommend
  additional repetitions before drawing conclusions
- Clarify ExtractAppIntentsMetadata is Xcode-driven and not suppressible
  from repo-local settings

2026-03-24 11:50:18 +01:00

2.8 KiB

Raw Blame History

Recommendation Format

All optimization skills should report recommendations in a shared structure so the orchestrator can merge and prioritize them cleanly.

Required Fields

Each recommendation should include:

title
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"
actionability -- classifies how fixable the issue is from the project (see values below)
category
observed_evidence
estimated_impact
confidence
approval_required
benchmark_verification_status

Actionability Values

Every recommendation must include an actionability classification:

repo-local -- Fix lives entirely in project files, source code, or local configuration. The developer can apply it without side effects outside the repo.
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.
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.
upstream -- Requires changes in a third-party dependency or external tool. The developer cannot fix it locally.

Suggested Optional Fields

scope
affected_files
affected_targets
affected_packages
implementation_notes
risk_level

JSON Example

{
  "recommendations": [
    {
      "title": "Guard a release-only symbol upload script",
      "wait_time_impact": "Expected to reduce your incremental build by approximately 6 seconds.",
      "actionability": "repo-local",
      "category": "project",
      "observed_evidence": [
        "Incremental builds spend 6.3 seconds in a run script phase.",
        "The script runs for Debug builds even though the output is only needed in Release."
      ],
      "estimated_impact": "High incremental-build improvement",
      "confidence": "High",
      "approval_required": true,
      "benchmark_verification_status": "Not yet verified",
      "scope": "Target build phase",
      "risk_level": "Low"
    }
  ]
}

Markdown Rendering Guidance

When rendering for human review, preserve the same field order:

title
wait-time impact
actionability
observed evidence
estimated impact
confidence
approval required
benchmark verification status

That makes it easier for the developer to approve or reject specific items quickly.

Verification Status Values

Recommended values:

Not yet verified
Queued for verification
Verified improvement
No measurable improvement
Inconclusive due to benchmark noise

2.8 KiB Raw Blame History