---
name: step-04-validate
description: Validation gate - APPROVED or REJECTED decision
model: haiku
prev_step: steps/step-03-specify.md
next_step: steps/step-05-handoff.md
---

<objective>
Validate that all specifications are complete and consistent.
Gate decision: APPROVED or REJECTED with reasons.
</objective>

## EXECUTION SEQUENCE

### 1. Read Current State

Read `{output_dir}/00-context.md` for state variables.
Read all previous outputs:
- `1-discovery.md`
- `2-business-requirements.md`
- `3-functional-specification.md`

Update progress: `04-validate` -> "In Progress"

---

### 2. Completeness Checklist

**Discovery validation:**
- [ ] Business problem clearly defined
- [ ] All stakeholders identified
- [ ] Scope (In/Out) explicit
- [ ] Acceptance criteria defined
- [ ] No critical open questions

**BRD validation:**
- [ ] All business objectives measurable
- [ ] All business rules have BR-ID
- [ ] Rules are testable (conditions + examples)
- [ ] Process flow documented
- [ ] Data entities complete

**FRD validation:**
- [ ] All UC have permission mapping
- [ ] All FR trace to BR
- [ ] Permission matrix complete
- [ ] UI wireframes provided
- [ ] Gherkin scenarios cover happy path + errors
- [ ] i18n keys defined for messages

---

### 3. Consistency Checks

**Cross-reference validation:**

| Check | Source | Target | Status |
|-------|--------|--------|--------|
| BR -> FR | 2-brd.md | 3-frd.md | {OK/FAIL} |
| AC -> UC | 1-discovery.md | 3-frd.md | {OK/FAIL} |
| Stakeholder -> Actor | 1-discovery.md | 3-frd.md | {OK/FAIL} |
| Entity -> Endpoint | 2-brd.md | 3-frd.md | {OK/FAIL} |

**Identify gaps:**
- BR without FR coverage
- AC without UC coverage
- Endpoints without permissions

---

### 4. SmartStack Convention Validation

**Permission path format:**
```
VALID:   business.{app}.{module}.{action}
INVALID: business.{app}.{action}
INVALID: {app}.{module}.{action}
```

**NavRoute compliance:**
- Controller route must match: `business.{app}.{module}`
- Permissions must use same base path

**Entity naming:**
- PascalCase for entity names
- Matches module naming convention

---

### 5. Risk Assessment

| Risk | Severity | Mitigation |
|------|----------|------------|
| {identified risk} | High/Medium/Low | {mitigation strategy} |

**Common risks to check:**
- [ ] Missing error handling for integrations
- [ ] Performance concerns for large datasets
- [ ] Security gaps in permission model
- [ ] Complex workflow without clear rollback

---

### 6. Make Decision

**APPROVED if:**
- All completeness checks pass (100%)
- All consistency checks pass
- No HIGH severity risks unmitigated
- SmartStack conventions respected

**REJECTED if:**
- Any critical completeness check fails
- Consistency gap found
- HIGH severity risk without mitigation
- Convention violations

---

### 7. Generate Validation Report

```json
{
  "featureId": "{feature_id}",
  "validatedAt": "{timestamp}",
  "validatedBy": "Business Analyst (Claude)",
  "decision": "APPROVED" | "REJECTED",
  "completeness": {
    "discovery": {
      "score": "5/5",
      "issues": []
    },
    "brd": {
      "score": "5/5",
      "issues": []
    },
    "frd": {
      "score": "6/6",
      "issues": []
    }
  },
  "consistency": {
    "brToFr": "OK",
    "acToUc": "OK",
    "stakeholderToActor": "OK",
    "entityToEndpoint": "OK"
  },
  "conventions": {
    "permissions": "OK",
    "navRoute": "OK",
    "naming": "OK"
  },
  "risks": [
    {
      "risk": "{description}",
      "severity": "Medium",
      "mitigation": "{strategy}",
      "status": "Mitigated"
    }
  ],
  "summary": "{Overall assessment}",
  "nextStep": "step-05-handoff" | "Revision required"
}
```

---

### 8. Save Output

Write to: `{output_dir}/validation.json`

Update `00-context.md`:
- Progress: `04-validate` -> "Complete"
- Add validation status

---

### 9. Handle Decision

**If APPROVED:**

Display:
```
VALIDATION - {feature_id}
├── Status: APPROVED
├── Completeness: 100%
├── Consistency: All checks passed
├── Conventions: SmartStack compliant
├── Risks: {count} mitigated
├── Output: {output_dir}/validation.json
└── Next: step-05-handoff (Development prompt)
```

Load next step: `steps/step-05-handoff.md`

**If REJECTED:**

Display:
```
VALIDATION - {feature_id}
├── Status: REJECTED
├── Issues found:
│   ├── {issue 1}
│   ├── {issue 2}
│   └── {issue 3}
├── Required actions:
│   ├── {action 1}
│   └── {action 2}
└── Next: Revise specifications
```

**Ask user:**
```json
{
  "questions": [
    {
      "question": "How would you like to proceed?",
      "header": "Action",
      "options": [
        {"label": "Auto-revise", "description": "Claude fixes the identified issues"},
        {"label": "Manual revision", "description": "You fix and relaunch validation"},
        {"label": "Force approval", "description": "Continue despite issues (not recommended)"}
      ],
      "multiSelect": false
    }
  ]
}
```

---

## OUTPUT

This step produces:
- `{output_dir}/validation.json` (created)
- `{output_dir}/00-context.md` (updated)

Gate decision enables or blocks next step.
