@atlashub/smartstack-cli 3.39.0 → 3.40.0

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

@@ -1,258 +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/{App}/business-analyse/v1.0/feature.json \
-  --output .ralph/prd-{ModuleCode}.json
-```
-
-**Example:**
-```bash
-ss derive-prd \
-  --feature docs/HumanResources/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
+# 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/{App}/business-analyse/v1.0/feature.json \
+  --output .ralph/prd-{ModuleCode}.json
+```
+
+**Example:**
+```bash
+ss derive-prd \
+  --feature docs/HumanResources/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