github/self
1
1
Fork 0
mirror of https://github.com/selfxyz/self.git synced 2026-04-27 03:01:15 -04:00
Code Issues Packages Projects Releases Wiki Activity

add prompt to enhance product spec (#1772)

Browse Source
This commit is contained in:
Justin Hernandez
2026-02-18 15:07:23 -08:00
committed by GitHub
parent 5cdf9df36d
commit f37c3e904c
1 changed files with 249 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

249
specs/PRODUCT-SPEC-ENHANCEMENT-PROMPT.md Normal file
View File

@@ -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 `<!-- path: -->` 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