Read CLAUDE.md for project context.

I'm building an iOS app called [App Name].

Here's the idea: [describe your app in 2-3 sentences — be specific, not aspirational]

Target users: [describe who uses this — their context, device habits, tech comfort level]
Core problem: [the specific pain this solves — one sentence]
Why iOS native: [why does this need to be a native app, not a web app or PWA]

Generate a full Idea Pack. Save to docs/idea-pack.md.

The Idea Pack must contain:

1. **Problem Statement**
   The specific problem, who has it, how they currently solve it (or don't), and why existing solutions fall short.

2. **Proposed Solution**
   What the app does, how it solves the problem, and what makes it different.

3. **Target Users**
   At least two specific user personas. For each: name, role, device habits, iOS proficiency, primary use context (commuting, desk, couch), key frustrations.

4. **User Stories**
   Minimum 8 user stories covering the full lifecycle (onboarding, core loop, edge cases, offboarding).
   Format:
   US-001: As a [persona], I want to [specific action] so that [measurable benefit]
   
   Each user story must be iOS-native — use swipe, tap-and-hold, haptic, notification, widget, and share sheet patterns where appropriate. Avoid stories that assume a keyboard and mouse.

5. **Key Features for v1**
   Ordered by user value. For each feature:
   - What it does
   - Why it's in v1 (not v2)
   - Any iOS-specific implementation notes (e.g. requires camera permission, uses HealthKit)

6. **Out of Scope for v1**
   Explicit list of things you are NOT building. This prevents scope creep.

7. **Success Metrics**
   How will you know this app is working? Include:
   - Activation metric (what does a successful first session look like)
   - Retention metric (what does week-2 usage look like)
   - App Store metric (target rating and review volume)

8. **iOS Platform Requirements**
   - Minimum iOS version and rationale
   - Device support (iPhone only / Universal / iPad required)
   - Permissions required (Camera, Location, Notifications, Contacts, Photos, HealthKit, etc.)
   - Offline behaviour — what works without a network connection
   - Background behaviour — does the app need background refresh, location, or processing
   - Privacy manifest requirements (list the APIs that need privacy manifest entries)
   - Any App Store category restrictions to be aware of

9. **App Store Positioning**
   - Primary category + subcategory
   - 3-5 keywords for App Store search
   - Competitive apps in the same category (name 3, note their weaknesses)
   - Why a user would choose this app over those

10. **Open Questions**
    List every assumption you're making that hasn't been validated. Flag the ones that would change the app significantly if wrong.

After creating the file, summarise the 3 most important open questions that need answers before we write the PRD.

# Commit the approved Idea Pack
git add docs/idea-pack.md
git commit -m "docs: idea pack approved"

Read the approved Idea Pack at docs/idea-pack.md and CLAUDE.md.
Create a full Product Requirements Document. Save to docs/prd.md.
Also create a separate acceptance checklist at docs/acceptance-checklist.md.

The PRD must contain all of the following sections:

---

1. **Overview**
   One paragraph. What are we building, for whom, and why now. No bullet points — write it as a paragraph that could appear in a press release.

2. **User Stories and Acceptance Criteria**
   Take every user story from the Idea Pack and expand it with numbered, testable acceptance criteria.

   Format:
   US-001: As a [user], I want to [action] so that [benefit]
   - AC-001.1: Given [context], when [action], then [expected result]
   - AC-001.2: Given [context], when [action], then [expected result]
   - AC-001.3: (edge case) Given [context], when [action], then [expected result]

   Rules:
   - Every user story MUST have at least one happy-path AC
   - Every user story MUST have at least one edge-case or error-state AC
   - ACs must be testable — "the user feels good" is not testable
   - iOS-specific ACs must name the exact gesture, permission prompt, or system behaviour
   - Include ACs for: empty state, loading state, error state, offline state (where applicable)

3. **Functional Requirements**
   Detailed list of what the system must do, organised by feature area.
   For each requirement:
   - Unique ID (FR-001, FR-002...)
   - Description
   - Which user stories it satisfies (e.g. "satisfies US-001, US-004")
   - Any iOS-specific constraints (permission required, iOS version minimum, SwiftData vs network)

4. **Non-Functional Requirements**
   - **Performance**: App launch time (<2s cold start), screen transition time (<300ms), list scroll performance (60fps minimum)
   - **Accessibility**: VoiceOver support for all interactive elements, Dynamic Type support (all text scales correctly to XXL), minimum 44x44pt touch targets, colour contrast ratio (WCAG AA minimum)
   - **Device support**: List every supported device size and iOS version
   - **Offline behaviour**: Which features work offline, which require connectivity, how conflicts are resolved when coming back online
   - **Data privacy**: What data is collected, where it's stored (on-device vs cloud), what happens when the user deletes the app, App Privacy Report requirements
   - **Battery and performance**: Background tasks must not run unnecessarily, location use must be justified

5. **Data Model**
   What data entities exist? What are their relationships? What are the key fields?
   
   For each entity:
   - Name and purpose
   - Key fields (name, type, required/optional, constraints)
   - Relationships to other entities
   - Whether it's stored locally (SwiftData), remotely (API), or both
   - Whether it needs to sync across devices (iCloud/CloudKit)

   If using SwiftData, show the @Model class structure.
   If using a backend API, show the database schema.

6. **API Contracts** (skip this section entirely if the app has no backend — note that explicitly)
   For apps with a backend, every endpoint must be documented precisely enough that a frontend developer and backend developer can build to them without talking to each other.
   
   For each endpoint:
   - Method and path
   - Auth requirement
   - Request body (field names, types, required/optional)
   - Response body (field names, types)
   - Status codes and what each means
   - Error response format
   
   Example format:
   POST /api/items
   Auth: Bearer token required
   Request: { "title": string (required), "notes": string (optional), "dueDate": ISO8601 string (optional) }
   Response 201: { "id": string, "title": string, "createdAt": ISO8601 string }
   Response 400: { "error": "validation_failed", "fields": ["title"] }
   Response 401: { "error": "unauthorized" }

7. **UI/UX Requirements**
   For each screen in the app:
   - Screen name and purpose
   - Entry points (how the user gets here)
   - Key elements visible on screen
   - Primary action
   - Navigation out (where the user can go from here)
   - iOS-specific patterns used (swipe to delete, long press menu, pull to refresh, etc.)
   - Empty state behaviour
   - Error state behaviour
   
   Also document:
   - Tab bar structure (if TabView) and what lives in each tab
   - Navigation stack depth limits
   - Modal vs push navigation decisions (and why)
   - Sheet vs full-screen cover decisions
   - Liquid Glass surfaces (which views get glass treatment, iOS 26+ gated)
   - Dark mode requirements

8. **Out of Scope**
   Explicit list of features NOT in v1. For anything tempting, add a sentence explaining why it's deferred.

9. **Dependencies**
   External services, APIs, and Swift packages required:
   - For each: name, purpose, SPM URL, free tier limits (if any), what breaks if it goes down
   - Apple frameworks required beyond UIKit/SwiftUI (HealthKit, MapKit, ARKit, StoreKit, etc.)
   - Any required Apple entitlements (Push Notifications, iCloud, Sign in with Apple, etc.)

10. **Phased Delivery Plan**
    Break the build into 3-6 phases. Each phase must be independently testable — you should be able to run the app and verify the phase is complete before starting the next.
    
    Phase 1 = minimum runnable version (navigation shell + one core feature end-to-end)
    
    For each phase:
    - What it delivers (user stories and functional requirements)
    - What can be built in parallel (separate Claude Code agents or teammates)
    - What must be sequential (dependencies)
    - Suggested agent team composition if parallelisable
    
    Format:
    Phase 1: [description]
    — Delivers: US-001, US-002 (FR-001 through FR-005)
    — Sequential (foundational setup — navigation, data model, auth if required)
    
    Phase 2: [description]
    — Delivers: US-003, US-004 (FR-006 through FR-012)
    — Parallelisable: SwiftData agent + UI agent + Test agent

---

After creating docs/prd.md, create a SEPARATE file at docs/acceptance-checklist.md.

The acceptance checklist must extract ALL acceptance criteria from the PRD into a flat checklist:
- [ ] AC-001.1: [full description]
- [ ] AC-001.2: [full description]
- [ ] AC-001.3: [full description]
- [ ] AC-002.1: [full description]
... and so on for every AC in the document.

This checklist is what we use to verify the build is complete before submitting to TestFlight.
Do not summarise or truncate. Include every AC.

# Commit the approved PRD and checklist
git add docs/prd.md docs/acceptance-checklist.md
git commit -m "docs: PRD and acceptance checklist approved"