# PRD v3.0 Structure & Validation Rules

Source: business-analyse step-05c-ralph-readiness.md

## PRD File Format v3.0

### File Location

```
.ralph/prd-{moduleCode}.json
```

Example: `.ralph/prd-Projects.json`, `.ralph/prd-TimeTracking.json`

---

## Structure Requirements

### 1. Version Field (MANDATORY)

```json
{
  "$version": "3.0.0"
}
```

**Validation:**
- MUST be exactly `"3.0.0"`
- BLOCKING if missing or wrong version

**Common Error:**
```
BLOCKING_ERROR: PRD version must be 3.0.0, got: 2.1.0
Fix: Re-run ss derive-prd with latest version
```

---

### 2. Implementation Section (MANDATORY)

**CRITICAL:** `filesToCreate` MUST be under `implementation`, NOT at root level.

**Correct Structure:**
```json
{
  "$version": "3.0.0",
  "implementation": {
    "filesToCreate": {
      "domain": [...],
      "application": [...],
      "infrastructure": [...],
      "api": [...],
      "frontend": [...],
      "seedData": [...],
      "tests": [...]
    }
  }
}
```

**Wrong Structure (v2.x legacy):**
```json
{
  "$version": "3.0.0",
  "filesToCreate": {  // ❌ WRONG - at root level
    "domain": [...]
  }
}
```

**Validation:**
- IF `prd.filesToCreate` exists at root level → BLOCKING ERROR
- IF `prd.implementation.filesToCreate` missing → BLOCKING ERROR

**Fix Command:**
```bash
ss derive-prd --feature {path} --output .ralph/prd-{moduleCode}.json
```

---

### 3. Seven Categories (MANDATORY)

All PRD files MUST include these 7 categories under `implementation.filesToCreate`:

| Category | Description | Examples |
|----------|-------------|----------|
| **domain** | Domain entities, value objects, domain services | `Project.cs`, `ProjectStatus.cs` |
| **application** | Application services, DTOs, interfaces | `ProjectService.cs`, `CreateProjectDto.cs` |
| **infrastructure** | Data access, repositories, EF Core config | `ProjectRepository.cs`, `ProjectConfiguration.cs` |
| **api** | Controllers, API endpoints | `ProjectsController.cs` |
| **frontend** | React pages, components, hooks | `ProjectsPage.tsx`, `useProjects.ts` |
| **seedData** | Seed data classes | `ProjectSeedData.cs` |
| **tests** | Unit tests, integration tests | `ProjectServiceTests.cs`, `ProjectsControllerTests.cs` |

**Validation:**
```javascript
const categories = ['domain', 'application', 'infrastructure', 'api', 'frontend', 'seedData', 'tests'];
const missingCategories = categories.filter(cat => !prd.implementation.filesToCreate[cat]);

if (missingCategories.length > 0) {
  BLOCKING_ERROR(`Missing categories: ${missingCategories.join(', ')}`);
}
```

**Common Errors:**
- Missing `tests` category → often forgotten
- Missing `seedData` category → sometimes omitted for modules without seed data
- Empty arrays allowed (e.g., `"seedData": []`) if genuinely no files needed

---

### 4. File Count Consistency (MANDATORY)

**Validation:** PRD file counts MUST match feature.json handoff counts.

```javascript
const featureHandoff = moduleFeature.handoff.filesToCreate;
const categories = ['domain', 'application', 'infrastructure', 'api', 'frontend', 'seedData', 'tests'];

for (const cat of categories) {
  const prdCount = prd.implementation.filesToCreate[cat]?.length ?? 0;
  const featureCount = featureHandoff[cat]?.length ?? 0;

  if (prdCount !== featureCount) {
    BLOCKING_ERROR(`${cat}: prd has ${prdCount} files but feature.json has ${featureCount}`);
  }
}
```

**Why this matters:**
- Ensures PRD was derived from the correct feature.json
- Catches stale PRD files (derived from old version)
- Validates handoff integrity before ralph-loop

**Fix:**
- Re-derive PRD from latest feature.json
- Check that feature.json handoff section is complete

---

### 5. File Entry Schema

Each file entry in a category array must have:

```json
{
  "path": "src/SmartStack.HumanResources.Domain/Projects/Project.cs",
  "type": "Entity",
  "module": "Projects"
}
```

**Required Fields:**
- `path` (string): Absolute or relative path where file will be created
- `type` (string): File type hint (Entity, Service, Controller, Page, Test, etc.)
- `module` (string): Module code this file belongs to

**Optional Fields:**
- `description` (string): Brief description of what the file does
- `dependencies` (array): Other files this depends on

---

## Validation Checklist

Use this checklist when validating PRD files:

| Check | Validation | Status |
|-------|-----------|--------|
| **Version** | `$version === "3.0.0"` | PASS/FAIL |
| **Structure** | `implementation.filesToCreate` exists (not root) | PASS/FAIL |
| **Categories** | All 7 categories present | PASS/FAIL |
| **File Counts** | PRD counts match feature.json handoff | PASS/FAIL |
| **File Schemas** | All files have path, type, module | PASS/FAIL |

**All checks must PASS before proceeding to /ralph-loop**

---

## Common Errors & Fixes

### Error 1: Wrong Version
```
BLOCKING_ERROR: PRD version must be 3.0.0, got: 2.1.0
```
**Fix:** Re-run `ss derive-prd` with latest SmartStack.mcp version

### Error 2: filesToCreate at Root Level
```
BLOCKING_ERROR: filesToCreate is at ROOT level (wrong structure)
```
**Fix:** Re-run `ss derive-prd --feature {path} --output .ralph/prd-{moduleCode}.json`

### Error 3: Missing Categories
```
BLOCKING_ERROR: Missing categories: seedData, tests
```
**Fix:**
- Check feature.json handoff.filesToCreate has all 7 categories
- Re-derive PRD after fixing feature.json
- If genuinely no files needed, use empty array: `"seedData": []`

### Error 4: File Count Mismatch
```
BLOCKING_ERROR: api: prd has 8 files but feature.json has 12
```
**Fix:**
- PRD is stale (derived from old feature.json)
- Re-derive PRD from latest feature.json: `ss derive-prd --feature {path} --output .ralph/prd-{moduleCode}.json`

---

## Generation Command Reference

**Derive PRD from feature.json:**
```bash
ss derive-prd \
  --feature docs/business/{App}/{Module}/business-analyse/v1.0/feature.json \
  --output .ralph/prd-{ModuleCode}.json
```

**Example:**
```bash
ss derive-prd \
  --feature docs/business/HumanResources/Projects/business-analyse/v1.0/feature.json \
  --output .ralph/prd-Projects.json
```

**Batch generation for all modules:**
```bash
# Typically done in step-05a-handoff.md
for module in $(modules); do
  ss derive-prd --feature {module_feature_path} --output .ralph/prd-${module}.json
done
```

---

## Why PRD Validation Matters

| Risk | Without Validation | With Validation |
|------|-------------------|-----------------|
| **Wrong structure** | ralph-loop fails mid-execution | Caught before development starts |
| **Stale PRD** | Generates code from old spec | Detects version mismatch |
| **Missing files** | Incomplete implementation | Ensures all layers covered |
| **Count mismatch** | Silent data loss | Guarantees integrity |

**Bottom line:** Ralph-loop depends on correct PRD structure. Validating upfront saves hours of debugging.

---

## Related Files

- `step-05a-handoff.md`: Generates PRD files via `ss derive-prd`
- `step-05c-ralph-readiness.md`: Validates PRD structure before ralph-loop
- `feature-schema.json`: Schema for feature.json (source of PRD)
- `/ralph-loop` skill: Consumes PRD files for implementation
