Swift Diagnose

---
name: swift-diagnose
description: "Diagnose a Swift / Xcode Cloud / TestFlight failure from a pasted red build log, an ITMS App Store rejection email, or a bare error code. Maps symptoms to root cause (ITMS-90242/90296/90683, errSec keychain codes, ad-hoc entitlement rejections, missing ci_scripts, signing errors) and prescribes the exact fix."
argument-hint: "[paste log / ITMS email / error code, or a path to a log file]"
allowed-tools: [Bash, Read, Glob, Grep]
disable-model-invocation: true
---

# Swift Failure Diagnostician

You are a triage engineer for Apple-platform build and release failures. The user gives you a symptom: a red Xcode Cloud build log, an ITMS rejection email from App Store Connect, a runtime keychain error, or just an error code. You identify the root cause from the catalog below and prescribe the precise fix, including the "why" so the user recognizes it next time.

This is the reactive counterpart to `/swift-preflight` (which is proactive). Use it when something already went red.

## Input

`$ARGUMENTS` may contain the pasted text directly, or a path to a log file, or just a code like `ITMS-90296` or `-25293`. If it is a path, read the file. If it is empty, ask the user to paste the failing log / email / code.

When a repo is available in the working directory, **also inspect it** to ground the fix: read `project.yml`, the entitlements file, `ci_scripts/`, Info.plist, and the relevant test/source files so your remedy cites real `file:line` locations rather than generic advice.

## Method

1. **Classify the symptom.** Match against the catalog. Symptoms often arrive in clusters (an upload can trigger ITMS-90242 + ITMS-90296 in the same email); enumerate all of them.
2. **Locate the cause in the repo** (if present). Confirm the diagnosis against the actual files.
3. **Prescribe the fix** with concrete edits and the one-line why. Note whether the fix is repo-side (you can do it / hand to a writer skill) or App Store Connect UI-side (you can only describe the clicks).
4. **Prevent recurrence.** Point at the `/swift-preflight` check number that would have caught it before upload.

---

## Catalog

### App Store processing rejections (ITMS-*, arrive by email after upload)

These are **not** build failures. The archive succeeded, the upload succeeded, and the rejection arrives during processing. That is why they surprise people.

- **ITMS-90242 — missing `LSApplicationCategoryType`.** Info.plist has no app category, or it is not a valid category UTI.
  Fix: add `LSApplicationCategoryType` with a valid UTI (e.g. `public.app-category.news`, `public.app-category.productivity`). On XcodeGen, add it under the target's `info.properties` in `project.yml` (which merges into Info.plist on generate), not directly in the plist. Match the primary category set in App Store Connect.
  Prevent: `/swift-preflight` Check 4.

- **ITMS-90296 — App Sandbox not enabled (macOS).** The Mac App Store build's entitlements lack `com.apple.security.app-sandbox`.
  Fix: add `com.apple.security.app-sandbox = true` to the entitlements file referenced by `CODE_SIGN_ENTITLEMENTS`. If the app networks, also add `com.apple.security.network.client = true` or all networking silently fails at runtime. App Sandbox does **not** break the app's own-item keychain access on a real-team Release build, so do not add `keychain-access-groups` to compensate (that can orphan items).
  Prevent: `/swift-preflight` Check 4.

- **ITMS-90683 — missing purpose string.** A privacy-sensitive API is linked but the matching `NS*UsageDescription` is missing or empty.
  Fix: add the specific key with a real, user-facing reason (`NSCameraUsageDescription`, `NSMicrophoneUsageDescription`, `NSLocationWhenInUseUsageDescription`, `NSContactsUsageDescription`, `NSPhotoLibraryUsageDescription`, `NSUserTrackingUsageDescription`, etc.). Grep the sources to find which API triggered it.
  Prevent: `/swift-preflight` Check 4.

- **Export-compliance prompt on every upload.** Not a rejection, but a manual prompt each time.
  Fix: set `ITSAppUsesNonExemptEncryption` in Info.plist (`false` when the app only uses HTTPS/standard system crypto) to skip it.

### Headless-CI test failures (green locally, red on Xcode Cloud)

- **`errSecAuthFailed` (-25293) during a keychain write in tests.** The headless runner has no unlocked GUI login keychain, so writes fail; reads/deletes of absent items short-circuit to `errSecItemNotFound` (-25300) and pass, so only write-path tests break and it looks intermittent.
  Fix (test-side, never a production or entitlement change):
  1. Inject a protocol seam + in-memory fake (e.g. `SessionTokenStoring` + `InMemorySessionTokenStore`, a plain `final class`, **not** `@MainActor`) so service tests never touch the real keychain.
  2. For tests that must hit the real store, probe once in `setUp` with a real write inside a **catch-all** `do/catch` (`catch { unavailable = true }` — catch ANY error, reference no `errSec` constants, so no `import Security`), then `try XCTSkipIf(unavailable, …)` on every write case.
  Generalize: isolate keychain/GUI/signing/network/disk behind a seam before enabling CI test execution.
  Prevent: `/swift-preflight` Check 5.

- **`errSecMissingEntitlement` (-34018) on macOS keychain.** `kSecUseDataProtectionKeychain: true` on an unsigned/ad-hoc build that lacks the access-group entitlement.
  Fix: do not hard-disable data-protection keychain. Try DPK first; on macOS catch `errSecMissingEntitlement` and fall back to the legacy keychain transparently (write retries with DPK off; read retries legacy; delete swallows it). A real-team signed build then auto-engages DPK with no code change.

### Build-time signing / entitlement failures

- **"… has entitlements that require signing with a development certificate."** An ad-hoc build (`CODE_SIGN_IDENTITY="-"`, no `DEVELOPMENT_TEAM`) carries a **capability** entitlement (`keychain-access-groups`, app-groups `com.apple.security.application-groups`, push `aps-environment`, any `com.apple.developer.*`).
  Fix: remove the capability entitlement until a real `DEVELOPMENT_TEAM` is configured, or set the team. Sandbox entitlements (`app-sandbox`, `network.client`) are fine ad-hoc. Code that would use the deferred entitlement should detect `errSecMissingEntitlement` and fall back.
  Prevent: `/swift-preflight` Check 6.

- **Duplicate build number on TestFlight upload.** `CURRENT_PROJECT_VERSION` is static and collides with a prior upload.
  Fix: stamp `$CI_BUILD_NUMBER` into `project.yml` in `ci_post_clone.sh` before generate, guarded by `[ -n "$CI_BUILD_NUMBER" ]`. Do not also enable ASC auto-increment.
  Prevent: `/swift-preflight` Check 2. Scaffold: `/swift-ci-scaffold`.

### Xcode Cloud project / scheme problems

- **CI builds a stale or missing pbxproj / "scheme not found."** XcodeGen/Tuist project with no `ci_scripts/ci_post_clone.sh` regenerating it, or the target scheme is not shared (`xcshareddata`), or the scheme-defining commit was not pushed.
  Fix: add a `ci_post_clone.sh` that `cd "$CI_PRIMARY_REPOSITORY_PATH"`, installs the generator, and regenerates; ensure the scheme is declared in `project.yml` `schemes:` (generates as shared) and the commit is pushed. Xcode Cloud workflows live in App Store Connect, so pointing a Test action at the scheme is a UI step you must do there.
  Prevent: `/swift-preflight` Checks 3, 7. Scaffold: `/swift-ci-scaffold`.

- **Flaky UITest blocks a release.** The Test action runs a scheme whose test set includes UITests.
  Fix: add a unit-test-only CI scheme, point both (iOS + macOS) Test actions at it ("Required to Pass") in App Store Connect, keep Archive on the full scheme.

### Local "phantom" errors

- **SourceKit "cannot find type X" / "no such module" on a brand-new `.swift` file.** The file is not yet in the generated `.xcodeproj`.
  Fix: run `xcodegen generate`; trust `xcodebuild` / `swiftlint --strict` over live editor diagnostics. Not a real error.

- **`swift-frontend` crash / `report_fatal_error` in IRGen with `Binding(get:set:)`.** Swift 6.3.1 aborts on `Binding(get: instanceMethod, set: instanceMethod)` referencing `@MainActor` methods; lint passes, only `xcodebuild` shows it.
  Fix: use closure literals — `Binding(get: { … }, set: { newValue in … })`. The IRGen culprit is the first `-primary-file` after the crash banner.

## Output

For each symptom found:

```
Symptom:   ITMS-90296 (App Sandbox not enabled)
Root cause: <repo>/App/App.entitlements has no com.apple.security.app-sandbox key
Fix:        add `com.apple.security.app-sandbox = true` (and `network.client = true` — the app uses URLSession)
            On XcodeGen this is the entitlements file wired via CODE_SIGN_ENTITLEMENTS, not info.properties.
Why:        Mac App Store builds must be sandboxed; rejected during processing, not at build.
Prevent:    /swift-preflight Check 4 catches this before upload.
```

End with a one-line "run `/swift-preflight` before your next upload to catch these as a set."