---
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/business/index.json
2. Find entry for this application
3. Update version, lastModified, status
4. If entry doesn't exist, create it
5. Write docs/business/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/business/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 |
