Mobile Release

---
name: mobile-release
description: "Mobile release capability pack. Covers App Store metadata & ASO, TestFlight distribution, review compliance checking, privacy policy & App Privacy Labels, version management, release CI/CD automation, and post-release monitoring. Use for any mobile app release, App Store submission, TestFlight beta, app review compliance, or release pipeline task."
version: 0.1.0
type: reference-based
keywords: ["App Store", "应用商店", "TestFlight", "iOS release", "iOS 发布", "上架", "fastlane", "EAS", "Expo", "app review", "审核", "rejection", "拒审", "privacy policy", "隐私政策", "privacy labels", "隐私标签", "ASO", "metadata", "元数据", "screenshots", "截图", "semver", "版本管理", "build number", "构建号", "release automation", "发布自动化", "crash monitoring", "崩溃监控", "评论回复"]
---

# Mobile Release Capability Pack

> From build to App Store — metadata, compliance, distribution, monitoring. iOS-primary, Android basic support. **Core value: prevent App Store review rejection BEFORE submission.**
> **CONSUMES**: An app project (Expo or native/RN CLI), Apple Developer Account, developer's answers about data practices.
> **PRODUCES**: Config files (Fastfile, eas.json, fastlane/metadata/) into the project directory; TAD documentation (compliance report, privacy policy, strategies) into `.tad/active/release/{project}/`.

---

## Step 1: Context Detection

| User Signal | Load Reference |
|---|---|
| metadata, title, keywords, screenshots, description, ASO, listing, 元数据, 关键词 | `references/store-metadata.md` |
| TestFlight, beta, build, sign, upload, certificates, match, 测试分发 | `references/testflight-distribution.md` |
| review, rejection, guideline, compliance, submit, 审核, 拒审, 上架检查 | `references/review-compliance.md` |
| privacy policy, privacy labels, data collection, COPPA, GDPR, SDK data, 隐私 | `references/privacy-policy.md` |
| version, semver, build number, tag, changelog, 版本号 | `references/version-management.md` |
| CI/CD, pipeline, GitHub Actions, automation, secrets, 自动化发布 | `references/release-automation.md` |
| crash, rating, reviews, monitoring, analytics, post-release, 崩溃, 评分 | `references/post-release-monitoring.md` |
| Gate review, reviewing a release deliverable, acceptance check, 验收 | `references/review-checklist.md` |

**Multi-signal**: Load all matched references. Before ANY Gate/expert review of release work → also load `references/review-checklist.md` (reviewer personas + Gate 2/Gate 4 checklists).

---

## Step 2: Decision Entry Point

**Q1 — What release stage?**
- Preparing store listing → `store-metadata.md`
- Getting a build to testers → `testflight-distribution.md`
- About to submit for review → `review-compliance.md` + `privacy-policy.md` (BOTH, always, before submission)
- Setting up repeatable releases → `version-management.md` + `release-automation.md`
- App already live → `post-release-monitoring.md`

**Q2 — What toolchain?**
- Expo project → EAS Build + EAS Submit (`eas build` / `eas submit`)
- Native / RN CLI → fastlane (`fastlane ios beta`, match, gym, pilot)
- CI/CD wanted → GitHub Actions + fastlane/EAS, or Xcode Cloud (Apple-native)
- Decision rule: **Expo = EAS, Native = fastlane.** Both need an Apple Developer Account.

**Q3 — Does the app have login?**
- Yes → a demo account for the Apple reviewer is MANDATORY (automatic rejection without one). Flag it now, not at submission time.

**Q4 — Does the app use AI, or have IAP/subscriptions?**
- AI → must disclose (2026 requirement, guideline 5.6.4) — check in `review-compliance.md`
- IAP/subscriptions → strict pricing transparency rules (guideline 3.1.1)

---

## Step 3: Hard Judgment Rules

These are pass/fail rules distilled from the pack's quality criteria. Violating any = the deliverable FAILS review.

### Store Metadata
- Title ≤ 30 chars (includes primary keyword); subtitle ≤ 30 chars (value proposition).
- Keywords ≤ 100 chars, comma-separated, no spaces after commas, no words duplicating the title.
- Screenshots MUST show the actual app (not mockups/renders), at required device sizes (6.7" + 6.1" minimum).
- Description first 3 lines must explain what the app does (visible without "more"). Feature-focused, not marketing fluff.
- Fabricated download numbers or invented reviews = FAIL.

### TestFlight Distribution
- Auth MUST use an App Store Connect API key (.p8), NEVER password (2FA breaks CI).
- Build number MUST be incremented before EVERY upload (duplicate = upload rejected).
- Certificates sync via fastlane match (encrypted git repo) — never shared ad-hoc.
- Verify end-to-end: build succeeds → upload succeeds → build visible in App Store Connect → testers can install.
- Fabricated build statuses or invented TestFlight URLs = FAIL.

### Review Compliance (CORE VALUE)
- Run the 10-item compliance checklist against THIS app BEFORE submission — every check cites a specific Apple guideline number (2.1, 2.3.1, 5.1.1, 3.1.1, 5.6.4...). Generic advice without guideline numbers = not a compliance check.
- Every FAIL item gets a specific, actionable fix (severity: blocking vs warning; effort: quick vs significant; blocking+quick first) — not "fix the bug".
- Login app → demo account for reviewer prepared.
- AI features → disclosure checked (new 2026 requirement).
- Fabricated compliance statuses or invented guideline numbers = FAIL.

### Privacy Policy
- MUST interrogate the developer BEFORE generating anything (SDK list from package.json/Podfile, account fields, permissions usage, AI/cloud data flow, children under 13, hosting URL). DO NOT PROCEED without answers — a privacy policy with wrong data categories is legally worse than none.
- App Privacy Labels MUST match actual data practices exactly, including EVERY third-party SDK (missing one = label mismatch = rejection).
- Policy must be app-specific (never a generic template) and hosted at an accessible URL (Apple requires it).
- Fabricated privacy claims or invented data practices = FAIL.

### Version Management
- Semantic versioning MAJOR.MINOR.PATCH (breaking/feature/fix); build number auto-increments on every TestFlight upload.
- Git tag `v{version}` on each release; app version must match Store listing version.
- Fabricated version numbers or skipped builds = FAIL.

### Release Automation
- Secrets (Apple API key, match passphrase, team ID) live in CI secrets storage, NEVER in code.
- Pipeline stages: lint → test → build → upload (never skip tests in CI).
- Verify from CI itself: trigger runs, build succeeds, upload succeeds, secrets not exposed in logs.
- Fabricated CI results or invented pipeline statuses = FAIL.

### Post-Release Monitoring
- Crash reporting (Sentry or Firebase Crashlytics) configured and tested — never ship blind.
- Alert thresholds: crash-free rate < 99%, rating < 4.0, downloads drop > 30% week-over-week.
- Respond to all 1-2 star reviews within 48h; never argue with reviewers; a human reviews and approves responses before posting.
- Fabricated monitoring data or invented crash rates = FAIL.

---

## Quick Rule Index

### Store Metadata (`references/store-metadata.md`)
- **4-step flow**: strategy (new vs `deliver download_metadata` vs localization) → create files → verify limits → ASO optimization
- **ASO rules**: use all 100 keyword chars, no cross-field word repeats, localize top markets (en/zh/ja/ko/de/fr)

### TestFlight Distribution (`references/testflight-distribution.md`)
- **Method selection**: Expo→EAS, Native→fastlane, CI→GitHub Actions + either
- **fastlane sequence**: match → increment_build_number → gym → pilot upload → pilot add
- **EAS sequence**: build:configure → build --platform ios → submit --latest

### Review Compliance (`references/review-compliance.md`)
- **10-item checklist table** with guideline numbers (crash, privacy labels, screenshots, links, IAP, performance, policy URL, AI disclosure, accessibility, latest Xcode)
- **4-layer flow**: search current guidelines → analyze against THIS app → prioritized fix plan → formatted report (PDF for stakeholders)

### Privacy Policy (`references/privacy-policy.md`)
- **Data practices matrix**: Data Type | Collected By | Purpose | Linked to User? | Tracking? → maps directly to App Privacy Labels
- **6 developer interrogation questions** — blocking gate before generation
- **8-section policy structure** (collect/why/storage/sharing/rights/contact/AI/COPPA)

### Version Management (`references/version-management.md`)
- **Setup per toolchain**: Expo app.json bump script vs native agvtool/fastlane increment lane
- **Automation**: CI build-number increment on merge, changelog from conventional commits, `1.0.0-beta.1` pre-releases

### Release Automation (`references/release-automation.md`)
- **Platform choice**: GitHub Actions + fastlane (flexible) vs EAS Build (no local Xcode) vs Xcode Cloud (Apple-native)
- **Setup detail**: setup_ci temporary keychain, EAS build profiles, caching, conditional submission on tags

### Post-Release Monitoring (`references/post-release-monitoring.md`)
- **Tool setup**: Sentry/Crashlytics, App Store Connect analytics, review monitoring (AppFollow)
- **Review response protocol** + iteration rules (top crashes → hotfix X.Y.Z+1)

### Review Checklist (`references/review-checklist.md`)
- **7 reviewer personas** with per-capability checklists (ASO Specialist, Release Engineer, Review Specialist, Privacy Officer, Release Manager, DevOps, PM)
- **Gate 2 / Gate 4 checklists** + expected release artifact structure

---

## Anti-Skip Table

| Shortcut Attempt | Required Action |
|---|---|
| "Let's just submit and see" | MUST run the 10-item checklist in `review-compliance.md` first — rejection costs a 1-7 day wait |
| "I'll write a standard privacy policy" | MUST interrogate the developer first per `privacy-policy.md` — wrong data categories are legally worse than none |
| "Password auth works locally" | MUST use App Store Connect API key (.p8) — password auth breaks in CI with 2FA |
| "Reuse the build number" | MUST increment before every upload — Apple rejects duplicate build numbers |
| "Fix the one thing Apple flagged" | MUST re-run the full checklist — partial fixes trigger re-rejection |
| "No one reads privacy labels" | MUST match labels to actual SDK behavior — mismatch is a top rejection reason |
| "We'll add crash reporting later" | MUST configure before release — otherwise blind to production issues |

---

## Anti-Patterns

### Store Metadata
- ❌ Screenshots showing features not in the app (guideline 2.3.1 rejection)
- ❌ Keywords duplicating title words (wasted characters)
- ❌ Marketing fluff description ('revolutionary', 'best ever')
- ❌ Missing required device screenshot sizes

### TestFlight Distribution
- ❌ Password auth (deprecated, 2FA issues in CI)
- ❌ Manual screenshot upload for multi-language
- ❌ Not incrementing build number (upload rejected)
- ❌ Sharing certificates via email (use fastlane match)

### Review Compliance
- ❌ Submitting without running compliance check (1-7 day wait if rejected)
- ❌ Partial fix for rejection issues (triggers re-rejection)
- ❌ No demo account for reviewer (automatic rejection if login required)
- ❌ Ignoring AI disclosure requirement (new in 2026)

### Privacy Policy
- ❌ Generic template privacy policy (must be app-specific)
- ❌ Privacy labels don't match actual behavior (top rejection reason)
- ❌ Missing third-party SDK data disclosure
- ❌ No accessible URL for privacy policy

### Version Management
- ❌ Manual version bumping (error-prone, forgettable)
- ❌ Same build number for multiple uploads (rejected)
- ❌ No git tags (can't trace what was in which release)

### Release Automation
- ❌ Secrets in code (API keys, certificates)
- ❌ No CI (manual build + upload every time)
- ❌ Skipping tests in CI (false confidence)

### Post-Release Monitoring
- ❌ No crash reporting (blind to production issues)
- ❌ Ignoring 1-star reviews (missed feedback + poor optics)
- ❌ No alert thresholds (find problems from user complaints, not data)