@atlashub/smartstack-cli 3.39.0 → 3.40.0

package/templates/skills/business-analyse/steps/step-06-review.md

@@ -1,278 +1,278 @@
----
-name: step-06-review
-description: Apply review corrections from ba-review.json, create new version, regenerate all artifacts
-model: opus
----
-
-> **Context files:** `_shared.md`, `references/review-data-mapping.md`, `references/html-data-mapping.md`
-
-# Step 06: Apply Review Corrections
-
-Apply corrections exported from the interactive HTML review (`ba-review.json`) to create a new version of the business analysis with all downstream artifacts regenerated.
-
-## Prerequisites
-
-- `workflow_type = "review"` (set by step-00)
-- `review_json_path` points to a valid `ba-review.json` file
-- `application_name` and `docs_dir` are set
-
-## Flow
-
-1. Read and validate ba-review.json
-2. Read existing master feature.json
-3. Create new version
-4. Apply cadrage corrections (reverse mapping)
-5. Apply module corrections
-6. Apply consolidation corrections
-7. Preserve review comments
-8. Regenerate PRD
-9. Regenerate progress.txt
-10. Update manifest
-11. Regenerate HTML
-12. Display completion summary
-
----
-
-## Step 1: Read and Validate ba-review.json
-
-```
-1. Read file at {review_json_path}
-2. Parse JSON
-3. Validate required structure:
-   - _reviewMeta: { sourceVersion, sourceApplicationId, exportedAt }
-   - metadata: { applicationId, version }
-   - cadrage: { ... }
-   - modules: [ ... ]
-   - moduleSpecifications: { ... }
-4. If validation fails → display error with missing fields, STOP
-5. Display: "Review file valid: {_reviewMeta.changeSummary}"
-```
-
-**Store:**
-```yaml
-review_data: parsed ba-review.json object
-source_version: _reviewMeta.sourceVersion
-change_summary: _reviewMeta.changeSummary
-```
-
-## Step 2: Read Existing Master Feature.json
-
-```
-1. Locate master feature.json from docs_dir
-2. Read and parse
-3. Verify metadata.application matches _reviewMeta.sourceApplicationId
-4. Store as existing_master
-```
-
-## Step 3: Create New Version
-
-Determine version bump based on changes:
-
-```
-IF change_summary.modulesAdded.length > 0 OR change_summary.modulesRemoved.length > 0:
-  version_type = "major"  (v1.0 → v2.0)
-ELSE:
-  version_type = "minor"  (v1.0 → v1.1)
-
-Call ba-writer.createVersion(existing_master.id, "Review corrections applied from v{source_version}")
-```
-
-**Store:**
-```yaml
-new_version: string (e.g., "1.1" or "2.0")
-new_docs_dir: path to new version directory
-new_master_path: path to new master feature.json
-```
-
-## Step 4: Apply Cadrage Corrections
-
-> **Reference:** `references/review-data-mapping.md` for exact field mapping
-
-Read the new master feature.json and apply reverse mapping from review data:
-
-```
-1. Scope mapping (review → feature.json):
-   - cadrage.scope.vital[] → cadrage.globalScope.mustHave[]
-   - cadrage.scope.important[] → cadrage.globalScope.shouldHave[]
-   - cadrage.scope.optional[] → cadrage.globalScope.couldHave[]
-   - cadrage.scope.excluded[] → cadrage.globalScope.outOfScope[]
-   (Extract name from {name, description} objects)
-
-2. Stakeholders mapping:
-   - For each review stakeholder:
-     - role → role (preserved)
-     - function → function
-     - tasks → tasks
-     - access → involvement (reverse: admin→decision-maker, manager→consulted, contributor→end-user, viewer→informed)
-     - frequency → frequency (reverse: daily→Quotidien, weekly→Hebdomadaire, monthly→Mensuel, occasional→Occasionnel)
-     - frustrations → painPoints (split by newline)
-
-3. Problem/Vision mapping:
-   - cadrage.problem.description → cadrage.problem
-   - cadrage.problem.trigger → cadrage.trigger
-   - cadrage.vision.changes → cadrage.toBe
-   - cadrage.current.tools → cadrage.asIs
-
-4. Risks mapping:
-   - For each review risk → cadrage.risks[] (direct mapping, generate RISK-NNN IDs if missing)
-
-5. Acceptance criteria:
-   - cadrage.success.definition → cadrage.acceptanceCriteria[] (split by newline, generate AC-NNN IDs)
-
-Call ba-writer.enrichSection(new_master.id, "cadrage", updated_cadrage)
-```
-
-## Step 5: Apply Module Corrections
-
-```
-FOR EACH moduleCode in review_data.moduleSpecifications:
-  1. Check if module exists in current master.modules[]
-     - If NEW module (in change_summary.modulesAdded):
-       a. Add to master.modules[] with metadata from review
-       b. Create module directory and feature.json via ba-writer.create(scope:"module")
-     - If REMOVED module (in change_summary.modulesRemoved):
-       a. Mark module status as "removed" in master (do NOT delete files)
-     - If EXISTING module:
-       a. Read module feature.json
-
-  2. Reverse-map module specification data:
-     - review.useCases[] → specification.useCases[]
-       (name→name, actor→primaryActor, steps→mainScenario (split by \n), alternative→alternativeScenarios)
-     - review.businessRules[] → analysis.businessRules[]
-       (name→name, category→category, statement→statement, example→examples[])
-     - review.entities[] → analysis.entities[]
-       (name→name, description→description, attributes→attributes, relationships→relationships)
-     - review.permissions[] → specification.permissionMatrix
-       (reverse "Role|Action" format → {permissions[], roleAssignments[]})
-
-  3. Write updated module feature.json via ba-writer.enrichSection()
-```
-
-## Step 6: Apply Consolidation Corrections
-
-```
-IF review_data.consolidation exists:
-  1. Reverse-map interactions:
-     - consolidation.interactions[] → consolidation.crossModuleInteractions[]
-       (from→fromModule, to→toModule, description→description)
-
-  2. Reverse-map E2E flows:
-     - consolidation.e2eFlows[] → consolidation.e2eFlows[]
-       (name→name, steps→steps, actors preserved)
-
-  Call ba-writer.enrichSection(new_master.id, "consolidation", updated_consolidation)
-```
-
-## Step 7: Preserve Review Comments
-
-Store all review feedback in a new `review` section of the master feature.json:
-
-```
-review_section = {
-  appliedAt: new Date().toISOString(),
-  sourceVersion: source_version,
-  comments: review_data.comments || [],          // inline structured comments
-  specComments: review_data.specComments || {},   // textarea comments per spec item
-  wireframeComments: review_data.wireframeComments || {},  // wireframe feedback
-  changeSummary: change_summary
-}
-
-Call ba-writer.enrichSection(new_master.id, "review", review_section)
-```
-
-## Step 8: Regenerate PRD
-
-```
-FOR EACH module in master.modules[] WHERE status != "removed":
-  Run: ss derive-prd --application {new_master_path} --module {moduleCode}
-  Verify: .ralph/prd-{moduleCode}.json exists and has filesToCreate
-```
-
-> `ss derive-prd` is a deterministic CLI command (no LLM), safe for regeneration.
-
-## Step 9: Regenerate progress.txt
-
-```
-Write .ralph/progress.txt with:
-- Link to new master feature.json
-- Link to each module feature.json
-- Link to ba-interactive.html (new version)
-- Summary of review changes applied
-```
-
-## Step 10: Update Manifest
-
-```
-1. Read docs/index.json
-2. Find entry for this application
-3. Update version, lastModified, status
-4. If entry doesn't exist, create it
-5. Write docs/index.json
-```
-
-## Step 11: Regenerate Interactive HTML
-
-> **Reference:** `references/html-data-mapping.md` for FEATURE_DATA and EMBEDDED_ARTIFACTS mapping
-
-```
-1. Read ba-interactive.html template from skill templates
-2. Build FEATURE_DATA from NEW master + module feature.json files
-   (follow exact mapping from html-data-mapping.md)
-3. Build EMBEDDED_ARTIFACTS from NEW module feature.json files
-   (wireframes, e2eFlows, dependencyGraph)
-4. Replace placeholders:
-   - {{FEATURE_DATA}} → serialized FEATURE_DATA JSON
-   - {{EMBEDDED_ARTIFACTS}} → serialized EMBEDDED_ARTIFACTS JSON
-   - {{APPLICATION_NAME}} → application_name
-   - {{APPLICATION_ID}} → feature_id
-5. Write to new version directory: {new_docs_dir}/ba-interactive.html
-```
-
-## Step 12: Display Completion Summary
-
-```
-═══════════════════════════════════════════════════════════════
-  REVIEW CORRECTIONS APPLIED SUCCESSFULLY
-═══════════════════════════════════════════════════════════════
-
-| Field                | Value                                |
-|----------------------|--------------------------------------|
-| Application          | {application_name}                   |
-| Previous version     | v{source_version}                    |
-| New version          | v{new_version}                       |
-| Version type         | {major/minor}                        |
-
-Changes applied:
-| Change               | Count                                |
-|----------------------|--------------------------------------|
-| Cadrage modified     | {yes/no}                             |
-| Modules added        | {count} ({list})                     |
-| Modules removed      | {count} ({list})                     |
-| Modules modified     | {count} ({list})                     |
-| Comments preserved   | {count}                              |
-
-Artifacts regenerated:
-| Artifact             | Path                                 |
-|----------------------|--------------------------------------|
-| Master feature.json  | {new_master_path}                    |
-| ba-interactive.html  | {new_docs_dir}/ba-interactive.html   |
-| PRD files            | .ralph/prd-*.json                    |
-| progress.txt         | .ralph/progress.txt                  |
-| Manifest             | docs/index.json                      |
-
-NEXT STEPS:
-1. Open the new ba-interactive.html to verify corrections
-2. Run /ralph-loop to start development from the updated analysis
-   (Use /ralph-loop -r ONLY to resume an interrupted loop)
-═══════════════════════════════════════════════════════════════
-```
-
-## Error Handling
-
-| Error | Action |
-|-------|--------|
-| ba-review.json malformed | Display structure errors, STOP |
-| Source version mismatch | Warn but continue (corrections may still apply) |
-| Module not found for update | Skip module, warn user |
-| PRD generation fails | Warn but continue (can be re-run manually) |
-| Manifest update fails | Warn but continue |
+---
+name: step-06-review
+description: Apply review corrections from ba-review.json, create new version, regenerate all artifacts
+model: opus
+---
+
+> **Context files:** `_shared.md`, `references/review-data-mapping.md`, `references/html-data-mapping.md`
+
+# Step 06: Apply Review Corrections
+
+Apply corrections exported from the interactive HTML review (`ba-review.json`) to create a new version of the business analysis with all downstream artifacts regenerated.
+
+## Prerequisites
+
+- `workflow_type = "review"` (set by step-00)
+- `review_json_path` points to a valid `ba-review.json` file
+- `application_name` and `docs_dir` are set
+
+## Flow
+
+1. Read and validate ba-review.json
+2. Read existing master feature.json
+3. Create new version
+4. Apply cadrage corrections (reverse mapping)
+5. Apply module corrections
+6. Apply consolidation corrections
+7. Preserve review comments
+8. Regenerate PRD
+9. Regenerate progress.txt
+10. Update manifest
+11. Regenerate HTML
+12. Display completion summary
+
+---
+
+## Step 1: Read and Validate ba-review.json
+
+```
+1. Read file at {review_json_path}
+2. Parse JSON
+3. Validate required structure:
+   - _reviewMeta: { sourceVersion, sourceApplicationId, exportedAt }
+   - metadata: { applicationId, version }
+   - cadrage: { ... }
+   - modules: [ ... ]
+   - moduleSpecifications: { ... }
+4. If validation fails → display error with missing fields, STOP
+5. Display: "Review file valid: {_reviewMeta.changeSummary}"
+```
+
+**Store:**
+```yaml
+review_data: parsed ba-review.json object
+source_version: _reviewMeta.sourceVersion
+change_summary: _reviewMeta.changeSummary
+```
+
+## Step 2: Read Existing Master Feature.json
+
+```
+1. Locate master feature.json from docs_dir
+2. Read and parse
+3. Verify metadata.application matches _reviewMeta.sourceApplicationId
+4. Store as existing_master
+```
+
+## Step 3: Create New Version
+
+Determine version bump based on changes:
+
+```
+IF change_summary.modulesAdded.length > 0 OR change_summary.modulesRemoved.length > 0:
+  version_type = "major"  (v1.0 → v2.0)
+ELSE:
+  version_type = "minor"  (v1.0 → v1.1)
+
+Call ba-writer.createVersion(existing_master.id, "Review corrections applied from v{source_version}")
+```
+
+**Store:**
+```yaml
+new_version: string (e.g., "1.1" or "2.0")
+new_docs_dir: path to new version directory
+new_master_path: path to new master feature.json
+```
+
+## Step 4: Apply Cadrage Corrections
+
+> **Reference:** `references/review-data-mapping.md` for exact field mapping
+
+Read the new master feature.json and apply reverse mapping from review data:
+
+```
+1. Scope mapping (review → feature.json):
+   - cadrage.scope.vital[] → cadrage.globalScope.mustHave[]
+   - cadrage.scope.important[] → cadrage.globalScope.shouldHave[]
+   - cadrage.scope.optional[] → cadrage.globalScope.couldHave[]
+   - cadrage.scope.excluded[] → cadrage.globalScope.outOfScope[]
+   (Extract name from {name, description} objects)
+
+2. Stakeholders mapping:
+   - For each review stakeholder:
+     - role → role (preserved)
+     - function → function
+     - tasks → tasks
+     - access → involvement (reverse: admin→decision-maker, manager→consulted, contributor→end-user, viewer→informed)
+     - frequency → frequency (reverse: daily→Quotidien, weekly→Hebdomadaire, monthly→Mensuel, occasional→Occasionnel)
+     - frustrations → painPoints (split by newline)
+
+3. Problem/Vision mapping:
+   - cadrage.problem.description → cadrage.problem
+   - cadrage.problem.trigger → cadrage.trigger
+   - cadrage.vision.changes → cadrage.toBe
+   - cadrage.current.tools → cadrage.asIs
+
+4. Risks mapping:
+   - For each review risk → cadrage.risks[] (direct mapping, generate RISK-NNN IDs if missing)
+
+5. Acceptance criteria:
+   - cadrage.success.definition → cadrage.acceptanceCriteria[] (split by newline, generate AC-NNN IDs)
+
+Call ba-writer.enrichSection(new_master.id, "cadrage", updated_cadrage)
+```
+
+## Step 5: Apply Module Corrections
+
+```
+FOR EACH moduleCode in review_data.moduleSpecifications:
+  1. Check if module exists in current master.modules[]
+     - If NEW module (in change_summary.modulesAdded):
+       a. Add to master.modules[] with metadata from review
+       b. Create module directory and feature.json via ba-writer.create(scope:"module")
+     - If REMOVED module (in change_summary.modulesRemoved):
+       a. Mark module status as "removed" in master (do NOT delete files)
+     - If EXISTING module:
+       a. Read module feature.json
+
+  2. Reverse-map module specification data:
+     - review.useCases[] → specification.useCases[]
+       (name→name, actor→primaryActor, steps→mainScenario (split by \n), alternative→alternativeScenarios)
+     - review.businessRules[] → analysis.businessRules[]
+       (name→name, category→category, statement→statement, example→examples[])
+     - review.entities[] → analysis.entities[]
+       (name→name, description→description, attributes→attributes, relationships→relationships)
+     - review.permissions[] → specification.permissionMatrix
+       (reverse "Role|Action" format → {permissions[], roleAssignments[]})
+
+  3. Write updated module feature.json via ba-writer.enrichSection()
+```
+
+## Step 6: Apply Consolidation Corrections
+
+```
+IF review_data.consolidation exists:
+  1. Reverse-map interactions:
+     - consolidation.interactions[] → consolidation.crossModuleInteractions[]
+       (from→fromModule, to→toModule, description→description)
+
+  2. Reverse-map E2E flows:
+     - consolidation.e2eFlows[] → consolidation.e2eFlows[]
+       (name→name, steps→steps, actors preserved)
+
+  Call ba-writer.enrichSection(new_master.id, "consolidation", updated_consolidation)
+```
+
+## Step 7: Preserve Review Comments
+
+Store all review feedback in a new `review` section of the master feature.json:
+
+```
+review_section = {
+  appliedAt: new Date().toISOString(),
+  sourceVersion: source_version,
+  comments: review_data.comments || [],          // inline structured comments
+  specComments: review_data.specComments || {},   // textarea comments per spec item
+  wireframeComments: review_data.wireframeComments || {},  // wireframe feedback
+  changeSummary: change_summary
+}
+
+Call ba-writer.enrichSection(new_master.id, "review", review_section)
+```
+
+## Step 8: Regenerate PRD
+
+```
+FOR EACH module in master.modules[] WHERE status != "removed":
+  Run: ss derive-prd --application {new_master_path} --module {moduleCode}
+  Verify: .ralph/prd-{moduleCode}.json exists and has filesToCreate
+```
+
+> `ss derive-prd` is a deterministic CLI command (no LLM), safe for regeneration.
+
+## Step 9: Regenerate progress.txt
+
+```
+Write .ralph/progress.txt with:
+- Link to new master feature.json
+- Link to each module feature.json
+- Link to ba-interactive.html (new version)
+- Summary of review changes applied
+```
+
+## Step 10: Update Manifest
+
+```
+1. Read docs/index.json
+2. Find entry for this application
+3. Update version, lastModified, status
+4. If entry doesn't exist, create it
+5. Write docs/index.json
+```
+
+## Step 11: Regenerate Interactive HTML
+
+> **Reference:** `references/html-data-mapping.md` for FEATURE_DATA and EMBEDDED_ARTIFACTS mapping
+
+```
+1. Read ba-interactive.html template from skill templates
+2. Build FEATURE_DATA from NEW master + module feature.json files
+   (follow exact mapping from html-data-mapping.md)
+3. Build EMBEDDED_ARTIFACTS from NEW module feature.json files
+   (wireframes, e2eFlows, dependencyGraph)
+4. Replace placeholders:
+   - {{FEATURE_DATA}} → serialized FEATURE_DATA JSON
+   - {{EMBEDDED_ARTIFACTS}} → serialized EMBEDDED_ARTIFACTS JSON
+   - {{APPLICATION_NAME}} → application_name
+   - {{APPLICATION_ID}} → feature_id
+5. Write to new version directory: {new_docs_dir}/ba-interactive.html
+```
+
+## Step 12: Display Completion Summary
+
+```
+═══════════════════════════════════════════════════════════════
+  REVIEW CORRECTIONS APPLIED SUCCESSFULLY
+═══════════════════════════════════════════════════════════════
+
+| Field                | Value                                |
+|----------------------|--------------------------------------|
+| Application          | {application_name}                   |
+| Previous version     | v{source_version}                    |
+| New version          | v{new_version}                       |
+| Version type         | {major/minor}                        |
+
+Changes applied:
+| Change               | Count                                |
+|----------------------|--------------------------------------|
+| Cadrage modified     | {yes/no}                             |
+| Modules added        | {count} ({list})                     |
+| Modules removed      | {count} ({list})                     |
+| Modules modified     | {count} ({list})                     |
+| Comments preserved   | {count}                              |
+
+Artifacts regenerated:
+| Artifact             | Path                                 |
+|----------------------|--------------------------------------|
+| Master feature.json  | {new_master_path}                    |
+| ba-interactive.html  | {new_docs_dir}/ba-interactive.html   |
+| PRD files            | .ralph/prd-*.json                    |
+| progress.txt         | .ralph/progress.txt                  |
+| Manifest             | docs/index.json                      |
+
+NEXT STEPS:
+1. Open the new ba-interactive.html to verify corrections
+2. Run /ralph-loop to start development from the updated analysis
+   (Use /ralph-loop -r ONLY to resume an interrupted loop)
+═══════════════════════════════════════════════════════════════
+```
+
+## Error Handling
+
+| Error | Action |
+|-------|--------|
+| ba-review.json malformed | Display structure errors, STOP |
+| Source version mismatch | Warn but continue (corrections may still apply) |
+| Module not found for update | Skip module, warn user |
+| PRD generation fails | Warn but continue (can be re-run manually) |
+| Manifest update fails | Warn but continue |