asc-submission-health ยท diff
git:20260329.893209f to git:20260910.90d1807
113 added, 146 removed. Audit A to A.
---
name: asc-submission-health
- description: Preflight App Store submissions, submit builds, and monitor review status with asc. Use when shipping or troubleshooting review submissions.
+ description: Diagnose App Store submission blockers and operate review health with asc, including readiness validation, repair routing, status monitoring, cancellation, and retry decisions. Use when validation fails, a version is not in a valid state, review status is unclear or stuck, or a failed submission must be repaired and retried. For staging, upload, publication, and submission execution, use asc-release-flow.
---
- # asc submission health
+ # App Store submission health
- Use this skill to reduce review submission failures and monitor status.
+ Use this skill to explain why a release cannot proceed and to manage an existing review submission. Hand healthy release execution back to `asc-release-flow`.
- ## Preconditions
- - Auth configured and app/version/build IDs resolved.
- - Build is processed (not in processing state).
- - All required metadata is complete.
+ ## Ownership boundary
- ## Pre-submission Checklist
+ This skill owns:
- ### 1. Verify Build Status
- ```bash
- asc builds info --build-id "BUILD_ID"
- ```
- Check:
- - `processingState` is `VALID`
- - `usesNonExemptEncryption` - if `true`, requires encryption declaration
+ - readiness validation and blocker diagnosis;
+ - public-API, web-session, and manual repair routing;
+ - review status and history;
+ - cancellation and retry decisions.
- ### 2. Encryption Compliance
- If `usesNonExemptEncryption: true`:
- ```bash
- # If the app should be exempt, patch the local plist helper, rebuild, and re-upload
- asc encryption declarations exempt-declare --plist "./Info.plist"
+ Use `asc-release-flow` for staging, upload, publication, and submission. Switching skills continues the current task with its resolved targets, authorization, and verified progress; it does not require the user to restart the workflow. Continue authorized repairs and return to release execution when healthy. Ask for new authority only when a repair exceeds scope.
- # List existing declarations
- asc encryption declarations list --app "APP_ID"
+ ## Answer order
- # Create declaration if needed
- asc encryption declarations create \
- --app "APP_ID" \
- --app-description "Uses standard HTTPS/TLS" \
- --contains-proprietary-cryptography=false \
- --contains-third-party-cryptography=true \
- --available-on-french-store=true
+ 1. State whether the version is ready, blocked, or already under review.
+ 2. Name each blocker and the evidence that proves it.
+ 3. Separate public-API repairs from web-session and manual work.
+ 4. Run the read-only checks needed to establish the diagnosis. For diagnosis-only requests, report the evidence and one proposed repair command without executing that repair. For authorized execution, continue the repair queue and report completed work and remaining blockers.
- # Assign to build
- asc encryption declarations assign-builds \
- --id "DECLARATION_ID" \
- --build "BUILD_ID"
- ```
+ ## Establish the target
- If the app truly uses only exempt transport encryption, prefer `asc encryption declarations exempt-declare --plist "./Info.plist"` and rebuild instead of creating a declaration that does not match the binary.
+ - Resolve `APP_ID`, the version string or `VERSION_ID`, `BUILD_ID`, platform, and any known `SUBMISSION_ID`.
+ - Configure auth with `asc auth login` or `ASC_*` environment variables.
+ - Use `ASC_BYPASS_KEYCHAIN=1` only for repository tests and isolated verification, not normal user sessions.
+ - Prefer IDs once the target is resolved; stop when app, version, or product resolution is ambiguous.
- ### 3. Content Rights Declaration
- Required for all App Store submissions:
- ```bash
- # Check current status
- asc apps content-rights view --app "APP_ID"
+ ## Diagnose readiness
- # Set it for most apps
- asc apps content-rights edit --app "APP_ID" --uses-third-party-content=false
- ```
- Valid values:
- - `DOES_NOT_USE_THIRD_PARTY_CONTENT`
- - `USES_THIRD_PARTY_CONTENT`
+ Run the canonical readiness report first:
- ### 4. Version Metadata
```bash
- # Check version details
- asc versions view --version-id "VERSION_ID" --include-build
-
- # Verify copyright is set
- asc versions update --version-id "VERSION_ID" --copyright "2026 Your Company"
+ asc validate --app "APP_ID" --version "1.2.3" --platform IOS --output table
```
- ### 5. Localizations Complete
- ```bash
- # List version localizations
- asc localizations list --version "VERSION_ID"
+ Use `--version-id "VERSION_ID"` when known. Add `--strict` when warnings must fail automation.
- # Check required fields: description, keywords, whatsNew, supportUrl
+ Ask the review-specific doctor for an ordered explanation:
+
+ ```bash
+ asc review doctor --app "APP_ID" --version "1.2.3" --platform IOS --output table
```
- ### 6. Screenshots Present
- Each locale needs screenshots for the target platform.
+ Collect direct evidence when the report points at the build or version:
- ### 7. App Info Localizations (Privacy Policy)
```bash
- # List app info IDs (if multiple exist)
- asc apps info list --app "APP_ID"
-
- # Check privacy policy URL
- asc localizations list --app "APP_ID" --type app-info --app-info "APP_INFO_ID"
+ asc builds info --build-id "BUILD_ID" --output table
+ asc versions view --version-id "VERSION_ID" --include-build --include-submission --output table
```
- ### 8. App Privacy readiness advisory
- `asc` can warn about App Privacy readiness, but the public App Store Connect API
- cannot verify whether App Privacy is fully published. Before final submission:
+ For digital goods, run only the relevant product validator:
```bash
- asc submit preflight --app "APP_ID" --version "1.2.3" --platform IOS
- asc validate --app "APP_ID" --version "1.2.3" --platform IOS
+ asc validate iap --app "APP_ID" --output table
+ asc validate subscriptions --app "APP_ID" --output table
```
- Prefer the version string form for top-level readiness checks in this skill so it stays aligned with `asc submit preflight`. Lower-level commands later in this guide still use `VERSION_ID` where the API requires it.
+ Treat the ordered remediation plan from `asc validate` as the repair queue. Fix and verify one class of blocker before moving to the next.
- If either command reports an App Privacy advisory, the public API cannot verify
- publish state. Use the web-session privacy workflow if you rely on those endpoints:
+ ## Route repairs
- ```bash
- asc web privacy pull --app "APP_ID" --out "./privacy.json"
- asc web privacy plan --app "APP_ID" --file "./privacy.json"
- asc web privacy apply --app "APP_ID" --file "./privacy.json"
- asc web privacy publish --app "APP_ID" --confirm
- ```
+ Use public API commands when the blocker is build processing, metadata, screenshots, review details, encryption, content rights, age rating, availability, or version-scoped product metadata.
- If you do not want to use the experimental `asc web privacy ...` commands,
- confirm App Privacy manually in App Store Connect:
+ Read [references/readiness-repairs.md](references/readiness-repairs.md) when diagnostics identify one of those common blockers or a first-release availability gap.
- ```text
- https://appstoreconnect.apple.com/apps/APP_ID/appPrivacy
- ```
+ Read [references/digital-goods.md](references/digital-goods.md) only when IAP or subscription validation fails, Apple requires first-review attachment, or a versioned product must join an existing review submission.
- ### 9. Digital goods readiness (IAPs / subscriptions)
- If the app sells subscriptions or in-app purchases, validate those separately before submit:
+ Read [references/app-privacy.md](references/app-privacy.md) only when validation reports an App Privacy advisory or the publish state cannot be confirmed through the public API.
- ```bash
- asc validate iap --app "APP_ID" --output table
- asc validate subscriptions --app "APP_ID" --output table
- ```
+ When validation reports a Game Center component or version blocker, hand it to `asc-release-flow` and request the multi-item reference's **Prepare every item** section. Do not route Game Center through general readiness or digital-goods repairs.
- In current asc, `asc validate subscriptions` expands `MISSING_METADATA` into a per-subscription diagnostics matrix. Use it to identify missing review screenshots, promotional images, pricing or availability coverage gaps, offer readiness, and app/build evidence before retrying submit or first-review attach.
+ Use the web-session commands only for a gap the public API cannot cover, and say that an authenticated Apple web session is required. Keep a manual App Store Connect fallback when the user declines web-session automation.
- Use `--output json --pretty` when you want exact territory gaps in machine-readable form.
+ ## Decide whether the version is healthy
- ## Submit
+ A version is ready to return to `asc-release-flow` when:
- ### Using Review Submissions API (Recommended)
- ```bash
- # Create submission
- asc review submissions-create --app "APP_ID" --platform IOS
+ - `asc validate` has no blocking issues;
+ - the attached build is `VALID`;
+ - metadata, screenshots, app info, review details, content rights, encryption, age rating, pricing, and availability are resolved;
+ - the relevant `asc validate iap` and/or `asc validate subscriptions` checks have no blocking issues, and the required digital-goods versions are prepared;
+ - any Game Center version items have been checked through `asc-release-flow`'s multi-item submission reference;
+ - App Privacy is confirmed or published.
- # Add version to submission
- asc review items-add \
- --submission "SUBMISSION_ID" \
- --item-type appStoreVersions \
- --item-id "VERSION_ID"
+ Do not call a version ready merely because one validator exits successfully. Report any warning that still needs a web-session or manual check.
- # Submit for review
- asc review submissions-submit --id "SUBMISSION_ID" --confirm
+ ## Monitor review
+
+ Use app-scoped status when the submission ID is unknown:
+
+ ```bash
+ asc review status --app "APP_ID" --version "1.2.3" --platform IOS --output table
```
- ### Using Submit Command
+ Use exact submission or version IDs when available:
+
```bash
- asc submit preflight --app "APP_ID" --version "1.2.3" --platform IOS
- asc submit create --app "APP_ID" --version "1.2.3" --build "BUILD_ID" --confirm
+ asc submit status --id "SUBMISSION_ID" --output table
+ asc submit status --version-id "VERSION_ID" --output table
```
- Use `--platform` when multiple platforms exist.
- ## Monitor
+ Use the release dashboard for surrounding build and review signals:
+
```bash
- # Check submission status
- asc submit status --id "SUBMISSION_ID"
- asc submit status --version-id "VERSION_ID"
+ asc status --app "APP_ID" --include builds,appstore,submission,review --output table
+ ```
- # List all submissions
- asc review submissions-list --app "APP_ID" --paginate
+ Use history to distinguish a current stall from earlier rejected or completed submissions:
+
+ ```bash
+ asc review history --app "APP_ID" --version "1.2.3" --paginate --output table
```
- ## Cancel / Retry
+ ## Cancel an unhealthy submission
+
+ Resolve the exact active submission before cancelling. Preview status first, then require confirmation:
+
```bash
- # Cancel submission
+ asc submit status --id "SUBMISSION_ID" --output table
asc submit cancel --id "SUBMISSION_ID" --confirm
-
- # Or via review API
- asc review submissions-cancel --id "SUBMISSION_ID" --confirm
```
- Fix issues, then re-submit.
- ## Common Submission Errors
+ When resolving by version, include the app for the modern review-submission lookup:
- ### "Version is not in valid state"
- Check:
- 1. Build is attached and VALID
- 2. Encryption declaration approved (or exempt)
- 3. Content rights declaration set
- 4. All localizations complete
- 5. Screenshots present for all locales
- 6. App Privacy has been reviewed and published in App Store Connect
+ ```bash
+ asc submit status --version-id "VERSION_ID" --output table
+ asc submit cancel --version-id "VERSION_ID" --app "APP_ID" --confirm
+ ```
- ### "Export compliance must be approved"
- The build has `usesNonExemptEncryption: true`. Either:
- - Upload export compliance documentation
- - Or rebuild with `ITSAppUsesNonExemptEncryption = NO` in Info.plist
+ The lower-level equivalent is valid when the exact review submission is already known:
- ### "Multiple app infos found"
- Use `--app-info` flag with the correct app info ID:
```bash
- asc apps info list --app "APP_ID"
+ asc review submissions-cancel --id "SUBMISSION_ID" --confirm
```
- ## Notes
- - `asc submit create` uses the new reviewSubmissions API automatically.
- - `asc submit preflight` can return non-blocking advisories; review them before submitting.
- - App Privacy publish state is not verifiable via the public API.
- - Prefer `asc apps content-rights view/edit` over ad-hoc app JSON inspection.
- - `asc validate subscriptions` now provides much richer per-subscription diagnostics for `MISSING_METADATA` cases.
- - If you use ASC web-session flows, `asc web privacy pull|plan|apply|publish` is the CLI path for App Privacy.
- - If you avoid the experimental web-session commands, confirm App Privacy manually in App Store Connect.
- - Use `--output table` when you want human-readable status.
- - macOS submissions follow the same process but use `--platform MAC_OS`.
+ Do not cancel a submission solely because review is taking longer than expected. Confirm the state and the user's intent first.
+
+ ## Decide when to retry
+
+ There is no dedicated retry command. Use this sequence:
+
+ 1. Cancel only if the active submission must be withdrawn.
+ 2. Repair the proven blockers.
+ 3. Re-run `asc validate` and the relevant product validators.
+ 4. Confirm no active submission already owns the version or review items.
+ 5. Hand the healthy version and any preserved `SUBMISSION_ID` to `asc-release-flow` for submission execution. Reuse an inspected `READY_FOR_REVIEW` draft; create a submission only when no matching draft or active submission exists.
+
+ ## Common failure routing
+
+ | Symptom | First evidence | Repair route |
+ | --- | --- | --- |
+ | Version is not in a valid state | `asc validate`, `asc review doctor` | ordered readiness repairs |
+ | Export compliance must be approved | build info and encryption declaration | readiness repairs |
+ | Multiple app infos found | `asc apps info list --app "APP_ID"` | resolve exact app-info ID |
+ | IAP or subscription is not ready | product validator | digital-goods reference |
+ | Game Center component or version is not ready | `asc validate` diagnostic | `asc-release-flow` multi-item preparation section |
+ | App Privacy publish state is unclear | validation advisory | App Privacy reference |
+ | Review appears stuck | review status plus history | monitor; cancel only with evidence and approval |
+
+ ## Guardrails
+
+ - Do not use removed `submit-preflight` or `submit-create` shortcuts.
+ - Do not submit from this skill; return healthy execution to `asc-release-flow`.
+ - Do not treat web-session automation as public App Store Connect API coverage.
+ - Do not retry until the earlier submission state and blocker repairs are verified.
+ - Use `--output table` for human diagnosis and JSON for automation.
+ - For macOS, use `--platform MAC_OS` while keeping the same health lifecycle.