prompt-enricher

name	prompt-enricher
description	Phase 0.2 — Enriches the raw user prompt with discovered constraints, ambiguities, likely edge cases, and suggested scope boundaries. Runs after context-gatherer, before idea-explorer questions. Generates enriched-prompt.md in the state directory.

Prompt Enricher

Runs automatically as Phase 0.2, after context-gatherer and before idea-explorer questions. Purpose: transform the raw user prompt into a grounded, constraint-aware brief that prevents the spec from ignoring known realities of the codebase.

Entry conditions

• context.md must exist in .claude/feature-state/{slug}/ (run context-gatherer first)
• Generates enriched-prompt.md and saves to .claude/feature-state/{slug}/
• Load if already exists (resume flow)

Step 1: Detect constraints from codebase

Read context.md and extract constraints relevant to the feature:

• Architectural constraints: What patterns must be followed? (e.g., "All API routes use verifyAuthRequest")
• Data constraints: What data model rules exist? (e.g., "soft delete only, never hard delete")
• Infrastructure constraints: What infrastructure is confirmed vs. uncertain? (e.g., "Stripe webhook is not configured in production")
• Dependency constraints: What libraries are already in use that shape the approach?

Step 2: Identify ambiguities

From the prompt + context, list decisions that have multiple valid interpretations:

Examples:

• "Use the existing checkout flow or create a new direct-connect mechanism?"
• "Should connection be pending/approved or immediate?"
• "Is this feature for trainers or students or both?"
• "Real-time list updates or on-load only?"

Step 3: Suggest likely edge cases by feature type

Auto-detect the feature type from the prompt and inject standard edge cases:

Feature type detected	Auto-suggested edge cases
Connection/relationship	What if already connected? What if connection is rejected?
Auth/permissions	What if token expired? What if user not found? Rate limit?
List/query	Empty result? Pagination? Combined filters? Sort order?
Form/input	Required vs optional fields? XSS/injection? Max length?
External integration	Timeout? Partial failure? Idempotency?
Delete/remove	Soft delete? Orphaned references? Permission check?
Notification	What if FCM token missing? Duplicate notification?
Payment	Idempotency? Webhook replay? Network failure mid-transaction?

Step 4: Suggest scope boundaries

Based on the prompt and the project's "Out of Scope" section in PROJECT.md:

• In scope (inferred from prompt + context)
• Likely out of scope (YAGNI — things often requested but not essential)
• Deferred (good ideas for a future iteration)

Step 5: Generate enriched-prompt.md

Save to .claude/feature-state/{slug}/enriched-prompt.md:

## Enriched Prompt

### Original Prompt
Allow personal trainers to connect with students after checkout

### Discovered Constraints
- All API routes must call verifyAuthRequest() before any operation (PROJECT.md)
- Firestore: soft delete only — status: 'archived', never hard delete
- Stripe webhook (handleCheckoutComplete) already creates trainer-student links
- FCM token not guaranteed — push notifications are optional

### Ambiguities to Resolve
- Should this create a NEW connection mechanism or extend the existing checkout flow?
- Is the connection immediate or does it require mutual acceptance?
- Should trainers see ALL their students or only active ones?
- Should students be notified when a trainer connects?

### Likely Edge Cases
- Trainer tries to connect with a student already connected → already-connected state
- Student belongs to multiple trainers → one-to-many or one-to-one relationship?
- Trainer with no students → empty state in CMS list
- Connection made, then Stripe payment reversed → what happens to the link?
- Real-time list update vs. stale view when trainer is on the CMS page

### Suggested Scope Boundaries
**In scope:**
- Trainer can see their connected students in /cms/students
- Student appears after successful checkout (existing mechanism)
- trainerId persisted on student Firestore document
- Student list loads on trainer CMS page

**Likely out of scope (YAGNI):**
- Student can view which trainer they're connected to (separate feature)
- Real-time listener for connection status (polling is sufficient for v1)
- Trainer can disconnect a student (follow-up feature)

**Deferred:**
- Push notification when connection is made (requires FCM token guarantee)
- Multiple trainers per student

Step 6: Inject into idea-explorer context

This file is made available to idea-explorer as its starting brief. When the enriched prompt exists, the first question from idea-explorer must reference it:

Based on what I found in the codebase, here's what we're working with:

[Summary of enriched-prompt.md key sections]

My first question: [first question anchored in the ambiguities above]

Edge case injection by feature type detection

Feature type is detected from keywords in the prompt:

Keywords	Detected type
connect, link, assign, bind, invite, follow	connection/relationship
login, auth, token, session, password, verify	auth/permissions
list, search, filter, query, paginate, find, show all	list/query
create, add, submit, form, input, register	form/input
stripe, payment, subscription, checkout, invoice	payment
delete, remove, archive, deactivate	delete/remove
notify, notification, push, email, alert	notification
webhook, API, external, integration, sync	external integration

Multiple types can be detected for a single feature.