ios-binary-size-reduction

name	ios-binary-size-reduction
description	Use when an iOS app binary/app package needs size reduction with risk-aware optimization, security-aware checks, and verifiable build/runtime evaluation so results are safe and repeatable.

iOS Binary Size Reduction

Use this skill for: Swift/Xcode apps where executable and package size are above target and size reduction must preserve app behavior, security, and startup quality.

0) Inputs

• workspace_or_project: .xcworkspace (preferred) or .xcodeproj
• scheme
• configuration: Release (default)
• risk_level: low | balanced | aggressive
• size_budget_mb: optional target reduction threshold
• min_gain_mb: minimum gain to keep a change (0.3 MB default)
• slice_scope: all or explicit family/OS slices

1) Guardrails

• Never apply unsafe production runtime settings: -Ounchecked, -enforce-exclusivity=unchecked, or equivalent safety suppression flags.
• Never remove dSYM generation. Keep symbol upload and crash-symbolication verified.
• Do not merge app behavior changes (asset migration, reflection, feature gating) without passing functional gates.
• Use one risk tier at a time; revert immediately on gate failure.
• Before edits, pin environment metadata (xcodebuild -version, swift --version, destination, git SHA) and rerun the baseline pipeline once as a no-op control.
• Capture and apply settings per target (for example: app target first, then extensions/widgets), not only project-level.

2) Baseline capture (required)

Before any mutation:

1. Collect build settings snapshot:
   • SWIFT_OPTIMIZATION_LEVEL
   • SWIFT_COMPILATION_MODE
   • DEAD_CODE_STRIPPING
   • STRIP_INSTALLED_PRODUCT
   • STRIP_SWIFT_SYMBOLS
   • LD / linker flags (OTHER_LDFLAGS)
   • ASSETCATALOG_COMPILER_OPTIMIZATION
   • ALWAYS_EMBED_SWIFT_STANDARD_LIBRARIES
   • SWIFT_REFLECTION_METADATA_LEVEL
   • LD_RUNPATH_SEARCH_PATHS
2. Capture size baselines from clean Release archive:
   • ipa size, app bundle size
   • Mach-O __TEXT and section split (xcrun size -m)
   • symbol table size, dSYM size
   • symbolication check against one controlled crash sample
3. Capture baseline quality/perf gates:
   • cold launch time and memory peak
   • targeted smoke suite pass/fail
   • launch crash/no-signature regressions
4. Record immutable environment metadata:
   • xcodebuild -version, swift --version
   • build destination (-destination)
   • git HEAD and clean/dirty state
   • scheme/configuration and archive variant
5. Use a reproducible baseline command template and reuse it verbatim for repeatability:
   • Workspace: xcodebuild -workspace "$WORKSPACE" -scheme "$SCHEME" -configuration Release -destination "$DESTINATION" -archivePath "$TMP_ARCHIVE" clean archive
   • Project fallback: xcodebuild -project "$PROJECT" -scheme "$SCHEME" -configuration Release -destination "$DESTINATION" -archivePath "$TMP_ARCHIVE" clean archive
   • Export: xcodebuild -exportArchive -archivePath "$TMP_ARCHIVE" -exportPath "$TMP_IPA_PATH" -exportOptionsPlist "$EXPORT_OPTIONS"

3) Pass scheduler (default execution order)

Tier 1 — Conservative

Apply in sequence, keep all gates green.

1. Run a deterministic Release-only pipeline only:
   1. clean
   2. archive (-configuration Release)
   3. fixed-name export of ipa
   • Compare only this Release archive pair against future Release artifacts; ignore Debug artifacts and ephemeral caches.
2. Enable deterministic post-processing: DEPLOYMENT_POSTPROCESSING = YES, STRIP_INSTALLED_PRODUCT = YES
3. STRIP_SWIFT_SYMBOLS = YES
4. DEAD_CODE_STRIPPING = YES
5. SWIFT_COMPILATION_MODE = WholeModule
6. Remove unused localizations and legacy assets only with an explicit locale/asset inventory
7. ASSETCATALOG_COMPILER_OPTIMIZATION = space, prune unused scales/device families; spot-check touched UI flows visually
8. Strip raster metadata (STRIP_PNG_TEXT = YES) where legal/compliance requirements allow it
9. Unembed or prune unnecessary resource-heavy bundles

Tier 2 — Performance/size tradeoff

Only enable if Tier 1 passes.

10. SWIFT_OPTIMIZATION_LEVEL = -Osize
11. Enable LLVM_LTO (incremental/partial first)
12. Slice pruning: remove unused architectures
13. Set ALWAYS_EMBED_SWIFT_STANDARD_LIBRARIES = NO only when precomputed target deployment matrix remains valid (per platform/extension/device family).
14. Dependency minimization pass (SPM/CocoaPods): remove unused targets/features/modules
15. App-thinning report validation and variant-specific packaging checks

Tier 3 — Conditional / high risk

Enable only with explicit approval when constraints are still missed. Required preconditions:

• Tier 1 and 2 must have passed two consecutive measured runs.
• Size delta trend must be stable (median repeat variance below configured noise floor).

16. SWIFT_REFLECTION_METADATA_LEVEL = without-names, then selective none
17. Symbol export hardening (GCC_SYMBOLS_PRIVATE_EXTERN, exported/unexported symbol map strategy)
18. Remove aggressive linker retention flags (-ObjC, -all_load) only after runtime validation
19. Move optional heavy payload to on-demand/background assets strategy
20. Framework split/restructuring or feature-module extraction where architecture allows

4) Technique catalogue with trade-off notes

• P1: Release-only clean baseline control. Low risk, required for valid deltas.
• P2: DEPLOYMENT_POSTPROCESSING and STRIP_INSTALLED_PRODUCT are deterministic, low-risk size wins.
• P3: STRIP_SWIFT_SYMBOLS = YES reduces size and improves artifact hygiene; requires strict dSYM retention.
• P4: DEAD_CODE_STRIPPING = YES gives medium-high size gain; low behavior risk with smoke tests.
• P5: Whole-module compilation is strong for dead boundaries; compile time can increase.
• P6: Localization pruning gives high ROI only with accurate usage inventory.
• P7: Asset catalog optimization is often highest ROI among Tier 1 items; visual regressions possible.
• P8: STRIP_PNG_TEXT = YES can improve size; preserve legal/compliance metadata.
• P9: Resource bundle pruning is strong but UX-sensitive.
• P10: -Osize is effective for binary shrink; potential hot-path performance regression.
• P11: LLVM_LTO typically improves size/perf but increases toolchain CPU/time.
• P12: Architecture pruning is deterministic if target matrix is validated.
• P13: ALWAYS_EMBED_SWIFT_STANDARD_LIBRARIES = NO lowers size where safe; verify all target configurations.
• P14: Dependency minimization has high value-to-effort, but functional side-effect risk is highest here.
• P15: App-thinning validation is low risk, high confidence for deployment compatibility.
• P16: Reflection metadata reduction is substantial, may break dynamic reflection users.
  • Validation checklist before and after enabling:
    • JSONDecoder/Decodable hot paths still roundtrip correctly
    • plugin/discovery paths using runtime type lookup
    • Mirror and dynamic cast behavior
    • serialization framework smoke paths (Codable/custom coders)
• P17: Export map hardening improves security posture but can break external integrations.
• P18: Removing -ObjC / -all_load is risky if runtime registration depends on it.
• P19: On-demand payload can greatly reduce install size; adds runtime fetch and fallback complexity.
• P20: Module/framework extraction improves long-term size/control but high refactor risk.

5) Security, quality, and performance comparison

• Security priority (best to worse): export hardening (P17) → deterministic stripping (P3,P4) → architecture/asset changes (P12,P7) → optimization/link choices (P10,P11) → reflection and linkage edits (P16,P18).
• Quality priority (best): resource and dependency cleanup (P6,P7,P14) → conservative compile/link toggles (P5,P10,P11) → reflection/payload changes (P16,P19).
• Perf priority (best): P11 and controlled reflection tuning (P16) are often neutral to positive; P10 can hurt hot paths.

6) Required validation gates after every pass

1. Size gate: ipa, app bundle, __TEXT, and install-eligible slices compared against baseline.
2. Functional gate: app launches + critical flows + startup path coverage.
3. Stability gate: controlled crash samples must symbolicate with uploaded dSYM.
4. Runtime gate: post-change launch and memory budgets respected.
5. Security gate: signing, entitlements, and crash-reportability unchanged.
6. Reversion gate: if actual gain < min_gain_mb or any gate fails, revert only that pass.

Gate execution rule:

• Run each gate twice (or one warm-up + one measured run at minimum); use median or stable mean for gate decisions.
• If either run is outlier by configured noise floor, rerun once before failing pass.

Default per-pass budgets unless overridden:

• size gain threshold: min_gain_mb (or 0.3MB)
• launch: +5% or +100ms
• memory peak: +10MB max
• critical flows: no regressions
• crash sample symbolication: 100%

7) Evaluation report format

Produce a single report per run containing:

• run_id, xcode_version, swift_version, git_sha, destination, risk_level
• run_started_at, run_ended_at, run_duration_seconds
• Baseline and final size rows (ipa, app, __TEXT, symbol bytes, dSYM bytes)
• Per-pass table entries:
  • pass_id
  • settings_changed
  • size_delta_mb
  • cumulative_gain_mb
  • pass_started_at, pass_ended_at, pass_duration_seconds
  • pass_status (applied, reverted, skipped)
  • security_impact
  • quality_impact
  • performance_delta
  • gate_status
  • rollback
  • notes
• Rollback log
• Final recommendation + confidence

8) Exit criteria and next-step policy

• Stop on first pass with acceptable reduction while all gates pass.
• If still above target, continue next tier.
• For low risk_level, never run P14 or above without explicit approval.
• For balanced, stop at tier 2 unless explicitly authorized.
• For aggressive, keep user-informed checkpoints before tier 3.

9) Minimal output JSON schema

{
  "run_id": "ios-size-YYYYMMDD-###",
  "xcode_version": "15.x",
  "swift_version": "5.x",
  "git_sha": "",
  "destination": "",
  "risk_level": "low|balanced|aggressive",
  "run_started_at": "2026-03-03T12:00:00Z",
  "run_ended_at": "2026-03-03T12:03:24Z",
  "run_duration_seconds": 204,
  "baseline": {
    "ipa_mb": 0.0,
    "app_mb": 0.0,
    "text_section_mb": 0.0,
    "symbols_mb": 0.0,
    "dsym_mb": 0.0
  },
  "final": {
    "ipa_mb": 0.0,
    "app_mb": 0.0,
    "text_section_mb": 0.0,
    "symbols_mb": 0.0,
    "dsym_mb": 0.0
  },
  "cumulative_gain_mb": 0.0,
  "passes": [
    {
      "id": "P4",
      "gain_mb": 0.0,
      "settings_changed": ["DEAD_CODE_STRIPPING=YES"],
      "size_delta_mb": 0.0,
      "cumulative_gain_mb": 0.0,
      "pass_started_at": "2026-03-03T12:01:00Z",
      "pass_ended_at": "2026-03-03T12:01:42Z",
      "pass_duration_seconds": 42,
      "pass_status": "applied",
      "security": "low|medium|high",
      "quality": "low|medium|high",
      "performance_delta": "improved|neutral|degraded",
      "gate_status": "pass|fail",
      "rollback": false,
      "notes": "reason"
    }
  ]
}