@atlashub/smartstack-cli 3.9.0 → 3.12.0

package/templates/skills/business-analyse/references/prd-generation.md

@@ -0,0 +1,258 @@
+# 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