Mobile Feature

Feature: [one-line name — e.g., "In-app push notification opt-in flow"]

## What and why

Problem
[What can't the user do today, or what's broken? On which platform(s) is this a problem?]

Who this is for
[Specific user type, platform, and context — e.g., "iOS users on v2.4+ who haven't enabled notifications"]

In scope
- [What this feature does]
- [Which platform(s) — iOS, Android, or both]
- [Minimum OS versions supported]

Out of scope
- [Platform explicitly excluded from this phase]
- [Device types not covered — e.g., "tablet layout not in scope"]
- [Features or settings not being touched]

Key behaviors
- When [user action], [outcome — specify if different per platform]
- When [permission is denied], [what the app does next]
- When [network is unavailable], [how the feature degrades]
- When [user backgrounds the app during this flow], [what happens on return]

Edge cases
- What happens when the user denies the required permission?
- What happens when the device has low storage or memory?
- What happens when the user is offline or on a slow connection?
- What happens when the app is force-quit mid-flow and reopened?
- What happens when the user switches between apps and returns?
- What's the behavior on the oldest supported OS version?
- Does the feature behave correctly in airplane mode?

Open questions
- [Is this iOS-only, Android-only, or both in this phase?]
- [Which permissions are required? Have they been declared in the app manifest / Info.plist?]
- [Does this feature need to work offline? What's the minimum required connectivity?]
- [Are there platform-specific UI guidelines that apply here — e.g., iOS Human Interface Guidelines?]

## Coding agent context

Tech stack
[e.g., "React Native 0.73, TypeScript, Expo SDK 50, react-navigation v6"]
[e.g., "Swift 5.9, UIKit, iOS 16+ minimum deployment target"]

Reference files
[e.g., "See /screens/NotificationSettings.tsx for existing permission request pattern"]
[e.g., "See /components/PermissionGate.tsx for the standard permission flow wrapper"]

Patterns to follow
- [e.g., "Follow the offline-first pattern in /hooks/useOfflineSync.ts — queue actions when offline, flush on reconnect"]
- [e.g., "Use the existing platform-specific styling pattern in /styles/platform.ts"]
- [e.g., "Navigation follows the stack pattern in /navigation/AppNavigator.tsx — do not introduce modal navigation without design review"]

Do not
- [ ] Do not assume network availability — handle degraded and offline states explicitly
- [ ] Do not block the main thread — async operations must run off the UI thread
- [ ] Do not request permissions without a clear contextual prompt explaining why
- [ ] Do not skip platform-specific behavior — test on both iOS and Android if both are in scope
- [ ] Do not ignore accessibility — VoiceOver (iOS) and TalkBack (Android) must navigate this feature correctly
- [ ] Do not hardcode screen dimensions — use responsive units and test on multiple screen sizes
- [ ] Do not introduce new third-party libraries without flagging — bundle size and licensing matter

Acceptance criteria
- [ ] Feature works correctly on the minimum supported iOS version
- [ ] Feature works correctly on the minimum supported Android version (if in scope)
- [ ] Feature degrades gracefully when offline — no blank screens or uncaught errors
- [ ] Permission denial is handled — user is not stuck or shown a broken state
- [ ] VoiceOver / TalkBack can navigate the feature without missing any interactive elements
- [ ] Feature works after the app is backgrounded and foregrounded mid-flow
- [ ] No new permissions are requested that aren't declared in the manifest / Info.plist
- [ ] Existing tests pass without modification