# BLUEPRINT: 0_BRAINSTORM → SPEC

**Goal:** Deeply understand the app and document ALL requirements before any code.

**Done when:** spec_template.md is COMPLETE with user flows, business rules, and entity relationships - AND user has validated it.

---

## CRITICAL: Do NOT Rush This Phase

**The #1 cause of wasted work is incomplete requirements.**

Before moving to Phase 1, you MUST have:
- [ ] Complete understanding of what users DO (not just what data exists)
- [ ] All user journeys mapped step-by-step
- [ ] Business rules and validations documented
- [ ] Entity relationships and state machines defined
- [ ] Edge cases and error scenarios considered

**If ANY of these are unclear, keep asking questions.**

---

## The Conversation Flow

```
User provides idea
    ↓
Agent asks IDENTITY questions (who, what, why)
    ↓
Agent asks USER JOURNEY questions (what do users DO step by step?)
    ↓
Agent asks DATA questions (what entities, relationships, states?)
    ↓
Agent asks BUSINESS RULES questions (validations, permissions, constraints)
    ↓
Agent asks EDGE CASE questions (what if X fails? what about Y?)
    ↓
Agent fills spec template
    ↓
Agent presents spec for validation
    ↓
User confirms OR agent asks more questions
```

---

## Question Categories (In Order)

### 1. IDENTITY (The "What")

Start broad, then narrow down:

- "Describe your app in one paragraph. What problem does it solve?"
- "Who is the primary user? Secondary users?"
- "What's the one thing a user MUST be able to do?"
- "What makes this different from [similar apps]?"

**Don't proceed until you can explain the app to someone else.**

---

### 2. USER JOURNEYS (The "How")

**This is the most important section.** Map what users actually DO.

For EACH user type, ask:
- "Walk me through a new user's first session. Step by step."
- "What's the most common task? Walk me through it."
- "What's the most complex task? Walk me through it."
- "What brings users back daily/weekly?"

**Document as numbered steps:**
```
## User Journey: Create a New Order

1. User clicks "New Order" button
2. User selects customer from dropdown (or creates new)
3. User adds products (search, quantity, notes)
4. User sees running total (auto-calculated)
5. User selects payment method
6. User clicks "Submit Order"
7. System validates stock availability
8. System creates order with status "pending"
9. User sees confirmation with order number
10. Customer receives email notification
```

**If you can't write this level of detail, you don't understand the app yet.**

---

### 3. DATA & ENTITIES (The "What Data")

For EACH entity, understand:

**Basic:**
- "What fields does [Entity] have?"
- "What's required vs optional?"
- "What are the valid values for [field]?"

**Relationships:**
- "How does [Entity A] relate to [Entity B]?"
- "Can [Entity] exist without [Related Entity]?"
- "When [Entity] is deleted, what happens to related data?"

**States:**
- "What statuses can [Entity] have?"
- "What triggers status changes?"
- "Can you go back from [status A] to [status B]?"

**Example state machine:**
```
Order States:
  draft → pending → confirmed → shipped → delivered
                  → cancelled (from pending or confirmed only)
                  → refunded (from delivered only)
```

---

### 4. BUSINESS RULES (The "Constraints")

Ask about validations and constraints:

- "What makes a [Entity] valid/invalid?"
- "What are the limits? (max items, max size, date ranges)"
- "What can't happen? What should be prevented?"
- "What triggers notifications/emails?"
- "What calculations happen automatically?"

**Document as rules:**
```
## Business Rules: Orders

- Order total = sum(item.price × item.quantity) + shipping - discount
- Discount cannot exceed 50% of subtotal
- Order cannot be cancelled after shipping
- Stock is reserved when order is confirmed, released if cancelled
- Customer email is sent on: order confirmed, order shipped, order delivered
```

---

### 5. PERMISSIONS (The "Who Can")

For EACH entity AND action:

- "Who can CREATE [Entity]?"
- "Who can VIEW [Entity]? All of them or only their own?"
- "Who can EDIT [Entity]? When?"
- "Who can DELETE [Entity]? Is it soft or hard delete?"

**Document as matrix:**
```
| Entity  | Create | Read      | Update    | Delete    |
|---------|--------|-----------|-----------|-----------|
| Product | admin  | everyone  | admin     | admin     |
| Order   | user   | owner     | owner*    | admin     |
| Review  | user   | everyone  | owner     | owner+admin|

* Order update only when status = draft
```

---

### 6. EDGE CASES (The "What If")

**Don't skip this.** Ask about failure scenarios:

- "What if [external service] is down?"
- "What if user submits invalid data?"
- "What if two users edit the same thing?"
- "What if user loses connection mid-action?"
- "What if [required field] is missing?"
- "What happens to old data when [schema changes]?"

---

### 7. NON-FUNCTIONAL (The "How Well")

- "How fast should [action] be?"
- "How many [entities] will exist? (10? 1000? 1M?)"
- "Who needs to be notified when [event]?"
- "What needs to work offline?"
- "What needs real-time updates?"

---

## Filling the Spec Template

Only after ALL questions are answered, fill `spec_template.md`:

1. **Identity** - Name, tagline, users
2. **User Journeys** - Step-by-step flows (NEW)
3. **Preset** - Based on app type
4. **Auth** - Providers, roles
5. **Billing** - If needed
6. **Entities** - With relationships and states (EXPANDED)
7. **Business Rules** - Validations, calculations (NEW)
8. **Pages** - Derived from user journeys
9. **Features** - i18n, PWA, etc.

---

## Validation: The Completeness Test

Before presenting spec to user, verify:

### Can You Answer These?

- [ ] "What does a new user do first?" → Have step-by-step answer
- [ ] "What's the main thing users do daily?" → Have step-by-step answer
- [ ] "What happens when [entity] status changes?" → Know all transitions
- [ ] "What validations exist on [entity]?" → Can list them
- [ ] "Who can [action] on [entity]?" → Know for every combination
- [ ] "What if [failure scenario]?" → Have answer for common failures

### Is The Spec Complete?

- [ ] Every entity has fields, relationships, states documented
- [ ] Every user journey has numbered steps
- [ ] Every business rule is explicit
- [ ] Every permission is defined
- [ ] No "TBD" or "TODO" in the spec

**If ANY checkbox is unchecked, ask more questions.**

---

## Presenting the Spec

When spec is complete, present it as:

```markdown
## App Specification Summary

### Identity
**Name:** [App Name]
**Purpose:** [One sentence]
**Users:** [Primary], [Secondary]

### Core User Journey
1. [First step]
2. [Second step]
...

### Entities
| Entity | States | Key Rules |
|--------|--------|-----------|
| [Name] | [States] | [Main validation] |

### Pages (derived from journeys)
- `/` - [Purpose]
- `/[route]` - [Purpose]

### Key Business Rules
1. [Rule 1]
2. [Rule 2]

### Open Questions (if any)
- [Question needing user input]

---
Does this capture your requirements completely?
What's missing or incorrect?
```

---

## Output

Completed spec_template.md with:
- All user journeys mapped
- All entities with relationships and states
- All business rules documented
- All permissions defined
- User validation

**Spec validated AND complete? Move to Phase 1: SCAFFOLD.**
**Anything unclear? Keep asking questions.**
