docs/requirements/mini-prd/[feature-name].md
├── Section 4: Scenarios       ← Markdown scenario specs
└── Section 5: Visual Specs    ← Storybook + RTL tests + Selector contract

Refinement phase (YOU ARE HERE):
  Write Markdown scenarios ──────────────────┐
  Define selector contract ──────────────────┤
                                             │
Delivery Phase (RED):                        │
  AI generates test files FROM scenarios: ◄──┘
    - E2E scenarios → Playwright specs
    - Integration scenarios → Jest tests
    - Component scenarios → RTL tests (often created in Refinement by ux-design-agent)
    - Unit scenarios → Jest tests

1. Read glossary file
   Location: /docs/glossary.yml or .claude/templates/glossary.yml
   Check all approved terms, synonyms, forbidden terms

2. Extract Linear issue details
   - Issue ID for reference in mini-PRD
   - Acceptance criteria as scenario seeds
   - User stories for actor identification

3. Identify scenarios from acceptance criteria
   For each acceptance criterion:
   - What's the happy path?
   - What errors could occur?
   - What edge cases exist?
   - What validation is needed?

4. Classify each scenario by test type
   Ask for each scenario:
   - Does it require real UI + real backend? → E2E
   - Does it test backend/API without UI? → Integration
   - Does it test component behavior? → Component
   - Does it test pure logic? → Unit

5. Write scenarios in Markdown format
   For each scenario:
   - Test Type label
   - Selector contract reference (if UI involved)
   - Preconditions (initial state)
   - Steps (user/system actions)
   - Expected (verifiable outcomes)

6. Review for glossary compliance
   - All terms match approved glossary
   - No synonyms used
   - No forbidden terms present

7. Verify coverage completeness
   - At least 1 happy path
   - Relevant error cases
   - Boundary conditions where applicable
   - Input validation where applicable

1. Load glossary file
   .claude/templates/glossary.yml or /docs/glossary.yml

2. Identify all domain terms in scenario
   - Nouns (customer, order, promo_code)
   - Verbs (apply, submit, cancel)
   - States (active, expired, pending)

3. Check each term against glossary
   For each term:
   - Is it an approved term? → Use exactly as defined
   - Is it a synonym? → Replace with approved term
   - Is it forbidden? → Must replace
   - Is it missing? → Request glossary update

4. Apply replacements
   Examples:
   - "shopper" → "customer" (synonym)
   - "voucher" → "promo_code" (forbidden)
   - "discount code" → "promo_code" (synonym)

5. Verify snake_case for compound terms
   - promo_code (not promoCode or promo-code)
   - order_total (not orderTotal)
   - Apply consistently across all scenarios

1. Ask: Is this a complete user journey through real UI + real backend?
   - YES → E2E (Playwright)
   - NO → Continue to step 2

2. Ask: Does this test backend/API behavior without UI?
   - YES → Integration (Jest + SDK)
   - NO → Continue to step 3

3. Ask: Does this test component behavior and user interaction?
   - YES → Component (RTL)
   - NO → Continue to step 4

4. It's pure logic/validation
   → Unit (Jest isolated)

Decision matrix:
┌────────────────────────────────────┬─────────────────┐
│ Scenario Type                      │ Test Type       │
├────────────────────────────────────┼─────────────────┤
│ User completes multi-page journey  │ E2E             │
│ Full signup → verify → dashboard   │ E2E             │
│ Cross-page navigation flow         │ E2E             │
├────────────────────────────────────┼─────────────────┤
│ JWT contains correct claims        │ Integration     │
│ Lambda creates tenant record       │ Integration     │
│ API returns correct error code     │ Integration     │
│ Cross-tenant access blocked        │ Integration     │
├────────────────────────────────────┼─────────────────┤
│ Button disables during submission  │ Component       │
│ Form shows validation errors       │ Component       │
│ Loading state displays correctly   │ Component       │
│ Accessible roles are correct       │ Component       │
├────────────────────────────────────┼─────────────────┤
│ Email format validation logic      │ Unit            │
│ Password strength calculation      │ Unit            │
│ Price discount calculation         │ Unit            │
│ Date formatting function           │ Unit            │
└────────────────────────────────────┴─────────────────┘

1. Check mini-PRD structure
   ✅ Section 4 contains scenarios
   ✅ Section 5 contains selector contract
   ✅ Links to Linear issue present

2. Check scenario coverage
   ✅ At least 1 happy path scenario
   ✅ At least 1 error scenario
   ✅ Relevant boundary scenarios (limits, edges)
   ✅ Relevant validation scenarios (input checking)

3. Check test type distribution
   Guideline (not strict enforcement):
   - Unit: ~50% of scenarios
   - Component: ~20% of scenarios
   - Integration: ~20% of scenarios
   - E2E: ~10% of scenarios

   Flag unusual distributions for discussion, but don't block.

4. Review scenario quality
   Each scenario:
   ✅ Uses domain language (not UI language)
   ✅ No implementation details leaked
   ✅ Clear actor identification
   ✅ Measurable, specific outcomes
   ✅ References selector contract (if UI involved)

5. Verify glossary compliance
   ✅ All domain terms match glossary
   ✅ No synonyms used
   ✅ No forbidden terms present
   ✅ Consistent snake_case for compound terms

6. Check acceptance criteria coverage
   For each Linear acceptance criterion:
   ✅ Mapped to at least one scenario
   ✅ Happy path tested
   ✅ Error cases considered

## Scenarios

### E2E: User signs up with valid email
**Test Type:** E2E (complete user journey)
**Selectors:** AUTH.signup.*

**Preconditions:**
- User is not logged in
- Email address not already registered

**Steps:**
1. User navigates to /signup
2. User enters valid email and strong password
3. User submits form

**Expected:**
- Verification email sent
- User sees "Check your email" message
- User record created in Cognito (unverified)

---

### Component: Signup form disables submit when password weak
**Test Type:** Component (RTL)
**Selectors:** AUTH.signup.*

**Preconditions:**
- SignupForm component rendered
- Email field has valid email

**Steps:**
1. User types weak password (e.g., "weak")

**Expected:**
- Submit button is disabled
- Password error message visible: "Password is too short"
- Error has accessible role

---

### Unit: Password validation rules
**Test Type:** Unit (pure logic)

**Test cases:**
| Input | Expected Result |
|-------|-----------------|
| "weak" | { valid: false, errors: ["Too short", "No uppercase", "No number"] } |
| "WeakPass1" | { valid: true, errors: [] } |
| "nouppercaseornumber" | { valid: false, errors: ["No uppercase", "No number"] } |

**Selectors:** AUTH.signup.*

// tests/selectors/auth.ts
export const AUTH = {
  signup: {
    form: 'signup-form',
    email: 'signup-email',
    password: 'signup-password',
    submit: 'signup-submit',
    successMessage: 'signup-success',
    passwordError: 'signup-password-error',
  },
};

### E2E: Apply valid promo_code at checkout
**Test Type:** E2E
**Selectors:** CHECKOUT.promo.*

**Preconditions:**
- Customer is signed in
- Cart contains items totaling $100
- Active promo_code "SAVE10" exists with 10% discount

**Steps:**
1. Customer navigates to checkout
2. Customer applies promo_code "SAVE10"

**Expected:**
- order_total reduced to $90
- Success message: "Promo code applied successfully"

### Test: Click apply button with code

**Steps:**
1. I'm on the checkout page
2. I type "SAVE10" in the promo code text box
3. I click the green "Apply" button

**Expected:**
- The total field shows $90
- A green success banner appears

### Integration: Customer receives order confirmation
**Test Type:** Integration

**Preconditions:**
- Customer has completed checkout
- Payment processed successfully

**Steps:**
1. System processes payment completion

**Expected:**
- Confirmation email sent within 30 seconds
- Order status is "confirmed"
- Order appears in customer's order history

### Test: Send email after payment

**Steps:**
1. Row exists in orders table with status='pending'
2. POST /api/payments returns 200 OK

**Expected:**
- INSERT into email_queue with template_id=5
- UPDATE orders SET status='confirmed' WHERE id=123

**Preconditions:**
- The customer has an active promo_code

**Steps:**
1. Customer applies the promo_code at checkout

**Expected:**
- order_total reflects the discount

**Preconditions:**
- The shopper has a valid voucher

**Steps:**
1. User enters the coupon code

**Expected:**
- Cart total is updated

### E2E: Successfully apply valid promo_code
**Test Type:** E2E
...happy path...

### E2E: Reject expired promo_code
**Test Type:** E2E
...expiration error...

### Integration: Reject already-used single-use promo_code
**Test Type:** Integration
...usage limit error...

### Integration: Promo_code with minimum order - just under
**Test Type:** Integration
...boundary case below minimum...

### Component: Promo input shows format error
**Test Type:** Component
...format validation...

### Unit: Promo_code format validation
**Test Type:** Unit
| Input | Expected |
|-------|----------|
| "SAVE10" | valid |
| "save-10" | invalid (lowercase, hyphen) |
| "" | invalid (empty) |

### E2E: Apply promo code
...only tests success case...

# Missing: error scenarios, boundaries, validation

### Component: Password field shows strength indicator
**Test Type:** Component (RTL)
**Selectors:** AUTH.signup.*

**Preconditions:**
- SignupForm component rendered
- Password field is empty

**Steps:**
1. User types "weak" in password field
2. User continues typing to "WeakPass1"

**Expected (after step 1):**
- Strength indicator shows "Weak"
- Indicator has aria-label "Password strength: weak"
- Submit button is disabled

**Expected (after step 2):**
- Strength indicator shows "Strong"
- Indicator has aria-label "Password strength: strong"
- Submit button is enabled