@atlashub/smartstack-cli 3.9.0 → 3.12.0

package/templates/skills/business-analyse/steps/step-05c-ralph-readiness.md

@@ -0,0 +1,518 @@
+---
+name: step-05c-ralph-readiness
+description: Validation gate before ralph-loop - verify completeness, integrity, and readiness
+model: sonnet
+next_step: null
+---
+
+> **Context files:** `_shared.md`
+
+# Step 5c: Ralph Readiness Check
+
+## MANDATORY EXECUTION RULES
+
+- **ALWAYS** run ALL validation checks (NEVER skip)
+- **BLOCKING RULE:** If ANY check fails → STOP, DO NOT proceed to ralph-loop
+- **ALWAYS** provide actionable fix instructions for failures
+- **NEVER** auto-launch ralph-loop (user triggers manually)
+- **ALL** PRD files must be generated and validated before proceeding
+
+## YOUR TASK
+
+Perform comprehensive validation to ensure the business analysis is ready for implementation via /ralph-loop. This is a **BLOCKING** gate - all checks must pass before development can proceed.
+
+---
+
+## EXECUTION SEQUENCE
+
+### 0. Introduction
+
+Display validation banner:
+
+```
+═══════════════════════════════════════════════════════════════
+  RALPH READINESS CHECK - {application_name}
+═══════════════════════════════════════════════════════════════
+Validating business analysis completeness before development...
+```
+
+---
+
+### 1. Module Status Validation
+
+**Objective:** Verify all modules have completed handoff.
+
+**Process:**
+
+1. Read master feature.json via ba-reader
+2. For EACH module in modules[]:
+   ```
+   a. Check module.status === "handed-off"
+   b. If module.featureJsonPath exists, read module feature.json
+   c. Verify module feature.json status === "handed-off"
+   d. Verify module feature.json handoff section exists and is not empty
+   ```
+
+3. Display validation table:
+
+```
+| Module | Master Status | Module Status | Handoff Present | Result |
+|--------|--------------|---------------|-----------------|--------|
+| Projects | handed-off | handed-off | ✓ | PASS |
+| TimeTracking | handed-off | handed-off | ✓ | PASS |
+| Reporting | specified | specified | ✗ | FAIL |
+```
+
+**IF ANY module shows FAIL:**
+- **BLOCKING ERROR:** List failed modules
+- **FIX:** Return to step-05a-handoff.md for missing modules
+- **STOP** - do not proceed to next check
+
+---
+
+### 2. PRD Files Validation
+
+**Objective:** Verify all PRD files are generated and structurally valid.
+
+**Process:**
+
+1. For EACH module in modules[]:
+   ```
+   a. Locate expected PRD file: .ralph/prd-{moduleCode}.json
+   b. Verify file exists
+   c. Read PRD file
+   d. Verify structure (see [references/prd-generation.md](../references/prd-generation.md))
+   ```
+
+2. **PRD Structure Validation:**
+
+   Perform the 4 mandatory PRD structure checks:
+   - **Check 1:** Version must be "3.0.0"
+   - **Check 2:** filesToCreate must be under `implementation` (NOT root level)
+   - **Check 3:** All 7 categories present (domain, application, infrastructure, api, frontend, seedData, tests)
+   - **Check 4:** File counts match feature.json handoff counts
+
+   ```javascript
+   const prdErrors = validateAllPRDs(modules);
+
+   IF prdErrors.length > 0:
+     // CONDITIONAL LOAD: Only load PRD reference on validation failure
+     Read references/prd-generation.md
+     Display:
+       - PRD v3.0 structure requirements
+       - Detailed validation logic for failed checks
+       - Common errors & fix commands for each failure
+       - Generation command reference
+
+     BLOCKING ERROR: {prdErrors.length} PRD file(s) invalid
+     → Fix all PRD errors before proceeding
+
+   ELSE:
+     All PRD files valid ✓
+     → Continue to dependency graph validation
+   ```
+
+   **Optimization:** The detailed 300-line prd-generation.md is loaded **only when PRD validation fails** (saves ~12,000 tokens on success path).
+
+3. Display PRD validation table:
+
+```
+| Module | PRD File | Version | Structure | File Counts | Result |
+|--------|----------|---------|-----------|-------------|--------|
+| Projects | ✓ exists | 3.0.0 | ✓ valid | 42/42 match | PASS |
+| TimeTracking | ✓ exists | 3.0.0 | ✓ valid | 37/37 match | PASS |
+| Reporting | ✗ missing | - | - | - | FAIL |
+```
+
+**IF ANY PRD shows FAIL:**
+- **BLOCKING ERROR:** List failed PRDs with specific issues
+- **FIX:** Re-run `ss derive-prd --feature {path} --output .ralph/prd-{moduleCode}.json`
+- **STOP** - do not proceed to next check
+
+---
+
+### 3. Dependency Graph Validation
+
+**Objective:** Verify module dependencies are resolvable and topologically ordered.
+
+**Process:**
+
+1. Read master feature.json dependencyGraph
+2. For each edge in dependencyGraph.edges[]:
+   ```
+   a. Verify source module exists in modules[]
+   b. Verify target module exists in modules[]
+   c. Verify no circular dependencies
+   ```
+
+3. Verify topologicalOrder matches actual dependencies:
+   ```
+   For each module M in topologicalOrder:
+     For each dependency D of M:
+       D must appear BEFORE M in topologicalOrder
+   ```
+
+4. Display dependency validation:
+
+```
+✓ Dependency graph valid
+✓ No circular dependencies detected
+✓ Topological order correct: [Projects, TimeTracking, LeaveManagement, AbsenceManagement, Reporting]
+✓ 4 dependency edges validated
+```
+
+**IF validation fails:**
+- **BLOCKING ERROR:** Report circular dependencies or invalid edges
+- **FIX:** Return to step-02-decomposition.md to fix dependency graph
+- **STOP** - do not proceed to next check
+
+---
+
+### 4. Cross-Module References Validation
+
+**Objective:** Verify all cross-module entity references are resolvable.
+
+**Process:**
+
+1. For EACH module feature.json:
+   ```
+   a. Extract all entity names from analysis.entities[]
+   b. Build map: {moduleName -> [entityNames]}
+   ```
+
+2. For EACH module feature.json:
+   ```
+   a. Extract all relationships from analysis.entities[].relationships[]
+   b. For each relationship.target:
+      - Extract module prefix (first segment before dot)
+      - Verify referenced module exists
+      - Verify referenced entity exists in target module
+   ```
+
+3. Display cross-reference validation:
+
+```
+Cross-Module References Validated:
+  ✓ TimeTracking.TimeEntry.projectId → Projects.Project.id
+  ✓ LeaveManagement.LeaveRequest.employeeId → Projects.Employee.id
+  ✓ AbsenceManagement.Absence.employeeId → Projects.Employee.id
+  ✓ Reporting.ProjectReport.projectId → Projects.Project.id
+
+Total: 4 cross-module references, all resolvable
+```
+
+**IF ANY reference is unresolvable:**
+- **BLOCKING ERROR:** List broken references with module and field names
+- **FIX:** Return to step-03a-data.md for affected modules to fix entity references
+- **STOP** - do not proceed to next check
+
+---
+
+### 5. Handoff Completeness Check
+
+**Objective:** Verify all required handoff sections are complete and non-empty.
+
+**Process:**
+
+For EACH module feature.json:
+
+1. **filesToCreate validation:**
+   ```
+   - handoff.filesToCreate must be an object
+   - All 7 categories must exist: domain, application, infrastructure, api, frontend, seedData, tests
+   - Each category must be a non-empty array
+   - Each file entry must have: path, type, module
+   ```
+
+2. **brToCodeMapping validation:**
+   ```
+   - handoff.brToCodeMapping must be a non-empty array
+   - Each entry must have: ruleId, files[], implementation
+   - All ruleIds must reference existing BRs in analysis.businessRules[]
+   ```
+
+3. **apiEndpointSummary validation:**
+   ```
+   - handoff.apiEndpointSummary must be a non-empty array
+   - Each entry must have: method, path, permission, linkedUC
+   - All linkedUCs must reference existing UCs in specification.useCases[]
+   ```
+
+4. **Metadata validation:**
+   ```
+   - handoff.complexity must be "simple|medium|complex"
+   - handoff.totalFiles must be > 0
+   - handoff.totalTasks must be > 0
+   - handoff.handedOffAt must be valid ISO timestamp
+   ```
+
+5. Display completeness summary:
+
+```
+Handoff Completeness:
+  Module: Projects
+    ✓ filesToCreate: 7 categories, 42 files total
+    ✓ brToCodeMapping: 8 business rules mapped
+    ✓ apiEndpointSummary: 12 endpoints documented
+    ✓ complexity: medium
+    ✓ metadata complete
+
+  Module: TimeTracking
+    ✓ filesToCreate: 7 categories, 37 files total
+    ✓ brToCodeMapping: 10 business rules mapped
+    ✓ apiEndpointSummary: 15 endpoints documented
+    ✓ complexity: complex
+    ✓ metadata complete
+```
+
+**IF ANY module has incomplete handoff:**
+- **BLOCKING ERROR:** List missing or invalid sections per module
+- **FIX:** Return to step-05a-handoff.md for affected modules
+- **STOP** - do not proceed to next check
+
+---
+
+### 6. i18n Keys Validation
+
+**Objective:** Verify all required i18n keys are defined for all 4 languages.
+
+**Process:**
+
+For EACH module feature.json:
+
+1. Extract all i18n keys from specification.i18nKeys[]
+2. Verify each key has translations for: fr, en, nl, de
+3. Check for common missing patterns:
+   ```
+   - Entity names (singular + plural)
+   - Field labels
+   - Validation error messages
+   - Success/error messages
+   - Navigation labels
+   - Button labels
+   ```
+
+4. Display i18n validation:
+
+```
+i18n Keys Validation:
+  Module: Projects
+    ✓ 42 keys defined
+    ✓ All keys have 4 languages (fr, en, nl, de)
+    ✓ Entity keys complete
+    ✓ Validation message keys complete
+    ✓ Navigation keys complete
+
+  Module: TimeTracking
+    ⚠ 37 keys defined
+    ⚠ Missing translation for "timeEntry.validation.overlapping" in DE
+    ✓ Entity keys complete
+```
+
+**IF ANY missing translations:**
+- **WARNING:** List missing translations (not blocking, but should be fixed)
+- **RECOMMEND:** Add missing translations before proceeding
+- Allow user to continue or fix
+
+---
+
+### 7. Master Feature Validation
+
+**Objective:** Verify master feature.json has all required application-level data.
+
+**Process:**
+
+1. Read master feature.json
+2. Verify status === "handed-off"
+3. Verify handoff section exists with:
+   ```
+   - implementationStrategy defined
+   - moduleOrder matches modules[]
+   - totalFilesToCreate === sum of all module totalFiles
+   - totalTasks === sum of all module totalTasks
+   - prdFiles array has entry for each module
+   ```
+
+4. Display master validation:
+
+```
+Master Feature Validation:
+  ✓ Status: handed-off
+  ✓ Implementation strategy: module par module
+  ✓ Module order: [Projects, TimeTracking, LeaveManagement, AbsenceManagement, Reporting]
+  ✓ Total files: 183 (matches sum of modules)
+  ✓ Total tasks: 247 (matches sum of modules)
+  ✓ PRD files: 5 (one per module)
+```
+
+**IF master validation fails:**
+- **BLOCKING ERROR:** List missing or invalid sections
+- **FIX:** Return to step-05a-handoff.md to fix master handoff
+- **STOP** - do not proceed
+
+---
+
+### 8. Progress Tracker Validation
+
+**Objective:** Verify progress.txt is generated and complete.
+
+**Process:**
+
+1. Verify file exists: `.ralph/progress.txt`
+2. Read file and verify structure:
+   ```
+   - Has header with application name
+   - Has summary section
+   - Has section for each module
+   - Each module section has tasks by layer
+   - Has completion checkboxes ([ ] format)
+   ```
+
+3. Count total tasks and verify matches master.handoff.totalTasks
+
+4. Display progress tracker validation:
+
+```
+Progress Tracker Validation:
+  ✓ File exists: .ralph/progress.txt
+  ✓ Size: 12.3 KB
+  ✓ Modules: 5 sections present
+  ✓ Tasks: 247 checkboxes (matches master)
+  ✓ Structure: valid markdown format
+```
+
+**IF progress tracker invalid:**
+- **WARNING:** Progress tracker issues (not blocking)
+- **RECOMMEND:** Re-generate via step-05b-deploy.md
+- Allow user to continue
+
+---
+
+### 9. Final Readiness Report
+
+**Objective:** Display comprehensive readiness summary and next steps.
+
+**Process:**
+
+1. Aggregate all validation results
+2. Calculate readiness score:
+   ```
+   passedChecks / totalChecks * 100
+   ```
+
+3. Display final report:
+
+```
+═══════════════════════════════════════════════════════════════
+  RALPH READINESS CHECK - COMPLETE
+═══════════════════════════════════════════════════════════════
+
+Validation Summary:
+  ✓ Module status validation: PASS (5/5 modules)
+  ✓ PRD files validation: PASS (5/5 files)
+  ✓ Dependency graph validation: PASS (4 edges)
+  ✓ Cross-module references validation: PASS (4 references)
+  ✓ Handoff completeness check: PASS (5/5 modules)
+  ⚠ i18n keys validation: WARNING (1 missing translation)
+  ✓ Master feature validation: PASS
+  ✓ Progress tracker validation: PASS
+
+Readiness Score: 100% (7/7 critical checks passed, 1 warning)
+
+═══════════════════════════════════════════════════════════════
+
+Status: READY FOR DEVELOPMENT ✓
+
+Next Steps:
+  1. Address warnings (recommended but not blocking):
+     - Add missing DE translation for "timeEntry.validation.overlapping" in TimeTracking module
+
+  2. Review progress tracker: .ralph/progress.txt
+
+  3. When ready, launch development:
+
+     /ralph-loop -r
+
+  4. Ralph-loop will:
+     - Process modules in topological order: [Projects, TimeTracking, LeaveManagement, AbsenceManagement, Reporting]
+     - Generate 183 files across 7 layers
+     - Execute 247 tasks tracked in progress.txt
+
+═══════════════════════════════════════════════════════════════
+```
+
+**IF readiness score < 100% (critical checks failed):**
+
+```
+═══════════════════════════════════════════════════════════════
+  RALPH READINESS CHECK - FAILED
+═══════════════════════════════════════════════════════════════
+
+Status: NOT READY FOR DEVELOPMENT ✗
+
+Critical Issues Found:
+  ✗ Module status validation: FAIL (1/5 modules incomplete)
+    - Reporting module status is "specified", must be "handed-off"
+    - Fix: Return to step-05a-handoff.md for Reporting module
+
+  ✗ PRD files validation: FAIL (1/5 files invalid)
+    - prd-Reporting.json has wrong structure (filesToCreate at root level)
+    - Fix: Re-run ss derive-prd --feature docs/business/HumanResources/Reporting/business-analyse/v1.0/feature.json --output .ralph/prd-Reporting.json
+
+Required Actions:
+  1. Fix all critical issues listed above
+  2. Re-run validation: load step-05c-ralph-readiness.md
+  3. Only proceed to /ralph-loop when all critical checks pass
+
+DO NOT PROCEED TO /ralph-loop UNTIL ALL CRITICAL CHECKS PASS
+═══════════════════════════════════════════════════════════════
+```
+
+---
+
+## SELF-VERIFICATION
+
+Before displaying final report, VERIFY:
+
+1. **ALL validation checks executed** (never skip)
+2. **Results clearly marked** (PASS/FAIL/WARNING)
+3. **Actionable fixes provided** for all failures
+4. **Readiness score calculated** correctly
+5. **Next steps displayed** with exact commands
+6. **Blocking errors prevent progression** (no false positives)
+
+---
+
+## SUCCESS CRITERIA
+
+- All 7 critical validation checks executed
+- Clear PASS/FAIL/WARNING status for each check
+- Readiness score displayed (100% = all critical checks passed)
+- Actionable fix instructions for all failures
+- User can proceed to /ralph-loop only if readiness score = 100%
+- Warnings documented but not blocking
+
+---
+
+## NOTES
+
+**Why this gate matters:**
+
+- Prevents incomplete handoffs from reaching development
+- Catches structural issues early (PRD validation)
+- Verifies cross-module integrity before code generation
+- Ensures ralph-loop has all required data to proceed
+- Reduces failed development attempts and rework
+
+**When to run this gate:**
+
+- Automatically at end of step-05b-deploy.md (recommended)
+- Manually before /ralph-loop if user wants to verify
+- After fixing any handoff issues to re-validate
+
+**What happens if checks fail:**
+
+- Development is BLOCKED until issues are fixed
+- User returns to appropriate step to fix issues
+- Re-run validation after fixes
+- Only proceed when all critical checks pass