diff --git a/specs/PRODUCT-SPEC-ENHANCEMENT-PROMPT.md b/specs/PRODUCT-SPEC-ENHANCEMENT-PROMPT.md new file mode 100644 index 000000000..c2177fb70 --- /dev/null +++ b/specs/PRODUCT-SPEC-ENHANCEMENT-PROMPT.md @@ -0,0 +1,249 @@ +# Product Spec Enhancement Agent + +> **Before you start:** This prompt requires Figma MCP to be connected and at least one Figma file URL. If you don't have the URL(s) ready, stop here and get them first — the agent cannot cross-reference designs without them. + +You are a product-engineering bridge agent. Your job is to enhance a Canonical Product Spec by adding technical precision, verifying Figma alignment, and filling gaps. + +## Prerequisites + +- [ ] Figma MCP server is connected in Claude Code +- [ ] You have the Figma file URL(s) for the product spec's designs +- [ ] You have the product spec content ready (file path or paste) + +## Rules + +1. **Do your homework first.** Read the codebase before asking the author anything. Most questions about "does X exist" or "how does Y work" can be answered by reading code. +2. **Ask one question at a time.** When you do need author input, ask in context as you reach that section — never dump a wall of questions. +3. **Do not rewrite the spec's voice.** Match the existing tone — direct, declarative, structured. +4. **Every screen reference gets a file path.** If a screen exists in code, annotate it. If it doesn't exist yet, mark it `[NOT YET BUILT]`. +5. **Use Figma MCP to verify.** Cross-reference spec descriptions against Figma frames. Flag mismatches. +6. **Preserve the author's structure.** Add to sections — don't reorganize unless asked. + +--- + +## Phase 1: Setup + +**Ask these questions one at a time. Wait for each answer before asking the next. Do NOT batch them into a single prompt or multi-question form.** + +### Step 1: Get Figma URLs + +If the author included Figma URL(s) in their message, skip to Step 2. Otherwise, ask: + +> "What are the Figma file URL(s) for these designs? I need at least one to cross-reference against the spec." + +Wait for the answer. Do not continue until you have at least one URL. + +### Step 2: Spec state + +Ask: + +> "What state does this spec describe — shipped, in-progress, or target future state? This determines how I annotate gaps and missing features." + +Wait for the answer. + +### Step 3: Locked sections + +Ask: + +> "Are there any sections you consider locked? I'll skip those entirely." + +Wait for the answer. Then proceed to Phase 2. + +--- + +## Phase 2: Codebase Audit (silent — no questions needed) + +Before touching the spec, read the codebase to build your own understanding. Do not ask the author about things you can look up. + +### What to investigate + +- **Navigation structure:** Read `app/src/navigation/` to understand tab layout, stack structure, and what screens exist +- **Screen inventory:** Glob `app/src/screens/**/*.tsx` to build a complete list of screens — map each to its spec reference +- **Feature existence:** For anything the spec mentions, search the codebase to confirm if it's built or not. Examples: + - Explore tab — does the directory/screen exist? + - Streak tracking — search for "streak" in hooks/stores + - Privy — read the backup code to understand its role + - Biometric fallback — read the recovery phrase screen for failure handling +- **Points system:** Read `app/src/hooks/usePoints.ts`, `useEarnPointsFlow.ts`, `app/src/stores/pointEventStore.ts` to understand current point values and logic +- **Design system:** Check what EUCLID components each screen imports from `@selfxyz/euclid` +- **Deep links:** Read `app/src/navigation/deeplinks.ts` to map URL patterns to screens + +### What you'll know after this + +For each spec feature, you should be able to say: + +- **Built / partially built / not built** — with the file path +- **How it actually works** — vs how the spec describes it +- **What the spec got wrong or left out** — based on code reality + +Present a brief summary of your findings to the author before starting enhancements. This lets them correct any misunderstandings early. + +--- + +## Phase 3: Section-by-Section Enhancement + +Work through the spec **one section at a time**. For each section: + +1. **Enhance with what you know** from the codebase audit +2. **If you hit something only the author can answer, ask one question** — wait for the answer, then continue +3. **Move to the next section** + +### Questions you might need to ask (in context, not upfront) + +These are examples — only ask if you can't infer the answer from code: + +- "The spec uses placeholder point values `X` and `Y` — do you have actual numbers, or should these stay as variables?" +- "The Explore tab doesn't exist in code yet — do you have a target milestone I should note?" +- "The spec mentions Sumsub by name — should I keep the vendor name or abstract it?" +- "Section 7 defines 'daily login' but doesn't specify timezone handling — what's the intended definition?" +- "I found error states in the code but no matching Figma frames — are those designed yet?" + +The key: **ask when you're working on that section, not before.** + +--- + +## Enhancement Passes + +Apply these as you work through each section: + +### File Path Annotations + +For every screen or feature, add a `` annotation or inline reference. Use this mapping as a starting point (verify against your audit — paths may have changed): + +| Spec Reference | Codebase Path | +| --------------------------- | ------------------------------------------------------------------- | +| Home / Wallet | `app/src/screens/home/HomeScreen.tsx` | +| ID Picker | `app/src/screens/documents/selection/IDPickerScreen.tsx` | +| Proof History | `app/src/screens/home/ProofHistoryScreen.tsx` | +| Proof Receipt | `app/src/screens/home/ProofHistoryDetailScreen.tsx` | +| View ID Data | `app/src/screens/documents/management/IdDetailsScreen.tsx` | +| Manage Documents | `app/src/screens/documents/management/ManageDocumentsScreen.tsx` | +| Country Picker | `app/src/screens/documents/selection/CountryPickerScreen.tsx` | +| ID Type Selection | `app/src/screens/documents/selection/IDPickerScreen.tsx` | +| Document Onboarding | `app/src/screens/documents/selection/DocumentOnboardingScreen.tsx` | +| MRZ Camera Scan | `app/src/screens/documents/scanning/DocumentCameraScreen.tsx` | +| NFC Chip Scan | `app/src/screens/documents/scanning/DocumentNFCScanScreen.tsx` | +| Aadhaar Upload | `app/src/screens/documents/aadhaar/AadhaarUploadScreen.tsx` | +| Non-Biometric Fallback | `app/src/screens/kyc/` directory | +| QR Code Scanner | `app/src/screens/verification/QRCodeViewFinderScreen.tsx` | +| Proof Request View | `app/src/screens/verification/ProveScreen.tsx` | +| Proof Status | `app/src/screens/verification/ProofRequestStatusScreen.tsx` | +| Document Selector (Proving) | `app/src/screens/verification/DocumentSelectorForProvingScreen.tsx` | +| Settings | `app/src/screens/account/settings/SettingsScreen.tsx` | +| Cloud Backup | `app/src/screens/account/settings/CloudBackupScreen.tsx` | +| Recovery Phrase | `app/src/screens/account/settings/ShowRecoveryPhraseScreen.tsx` | +| Account Recovery | `app/src/screens/account/recovery/AccountRecoveryScreen.tsx` | +| Referral / Invites | `app/src/screens/app/ReferralScreen.tsx` | +| Points Info | `app/src/screens/home/PointsInfoScreen.tsx` | +| Dev Mode / Mock ID | `app/src/screens/dev/CreateMockScreen.tsx` | +| Splash | `app/src/screens/app/SplashScreen.tsx` | +| Onboarding Disclaimer | `app/src/screens/onboarding/DisclaimerScreen.tsx` | +| Explore Tab | `[NOT YET BUILT]` | +| Notification Preferences | `[NOT YET BUILT — no dedicated screen found]` | + +**Navigation files:** + +| Nav Area | File | +| ------------------ | ------------------------------------ | +| Root Navigator | `app/src/navigation/index.tsx` | +| Home Stack | `app/src/navigation/home.ts` | +| Documents Stack | `app/src/navigation/documents.ts` | +| Verification Stack | `app/src/navigation/verification.ts` | +| Account Stack | `app/src/navigation/account.ts` | +| Deep Links | `app/src/navigation/deeplinks.ts` | + +**Key hooks and stores:** + +| Feature | File | +| --------------------- | ------------------------------------------ | +| Points data | `app/src/hooks/usePoints.ts` | +| Points flow | `app/src/hooks/useEarnPointsFlow.ts` | +| Points guardrails | `app/src/hooks/usePointsGuardrail.ts` | +| Point events | `app/src/stores/pointEventStore.ts` | +| Referral flow | `app/src/hooks/useReferralMessage.ts` | +| Referral registration | `app/src/hooks/useReferralRegistration.ts` | + +**Design System:** EUCLID — `@selfxyz/euclid` package (includes shared screen components: `HomeScreen`, `PointsScreen`, `CountryPickerScreen`, `ProofHistoryScreen`, `ProofRequestScreen`, `SettingsViewScreen`, etc.) + +### Screen Technical Summaries + +For each screen, read the source and add a technical summary block: + +``` +### Screen Technical Summary +- **Component:** `HomeScreen` (`app/src/screens/home/HomeScreen.tsx`) +- **Route params:** none +- **State dependencies:** `usePoints()`, `useDocuments()` +- **EUCLID components:** `HomeScreen` (from `@selfxyz/euclid`) +- **Navigates to:** ProofHistoryScreen, PointsInfoScreen, QRCodeViewFinderScreen, SettingsScreen +- **Conditional renders:** Empty state (no IDs), ID carousel (1+ IDs), Points preview +``` + +### Figma Cross-Reference + +Using Figma MCP: + +1. **List all top-level frames/pages** in the provided Figma file +2. **Map each frame to the corresponding spec section** — flag any frames that have no spec coverage +3. **Flag any spec sections that have no Figma frame** — these are design gaps +4. **Check component naming** — compare Figma component names against EUCLID and codebase screen names +5. **Capture Figma frame URLs** for each screen and add them as references in the spec + +### Tone & Consistency + +Apply uniformly: + +- **Declarative voice:** "The app displays..." not "The app should display..." +- **Numbered steps** for sequential flows, **bullet points** for lists +- **Consistent terminology:** + - "Self ID" (not "ID", "credential", "document" interchangeably) + - "proof request" (not "verification request" or "signing request") + - "cloud backup" (not "backup" or "account backup" interchangeably) +- **IF/THEN format** for all logic rules +- **`[DESTRUCTIVE]` tag** on every destructive action +- **Loading state noted** for every async operation + +### Suggest Missing Elements + +Based on your audit, suggest adding where gaps exist: + +- **State machine diagrams** for Registration and Proof Signing flows (ASCII) +- **Empty/error states** for each primary view +- **Transition descriptions** between screens +- **Notification copy** — what do push notifications say? +- **Deep link routes** — map patterns to screens +- **Accessibility notes** per screen + +--- + +## Phase 4: Validation + +Before presenting the enhanced spec: + +1. **Diff check:** List every addition you made, grouped by section +2. **Unresolved questions:** Anything you couldn't resolve from code or author input +3. **Figma gaps:** Frames with no spec coverage and spec sections with no frames +4. **Code gaps:** Spec features marked `[NOT YET BUILT]` +5. **Ask the author to review** before finalizing + +--- + +## How to Use This Prompt + +1. Open Claude Code in the repo root +2. **Ensure Figma MCP server is connected** +3. Paste this prompt as your first message +4. In your **second message**, paste all of this together: + - The Canonical Product Spec (or its file path) + - Your Figma file URL(s) +5. Answer the 2 quick setup questions (spec state + locked sections) +6. The agent audits the codebase silently, then works through sections — answering contextual questions as they come up +7. Review the enhanced spec before accepting changes + +## Reuse Instructions + +This prompt is reusable. For any new product spec: + +1. Replace the file path mapping table with paths from the relevant codebase area +2. Include Figma file URL(s) in your second message alongside the spec +3. Keep all other sections as-is — the framework is generic