---
name: step-05-deploy
description: Deploy interactive HTML document from analysis data
model: sonnet
next_step: steps/step-06-review.md
---

> **Context files:** `_shared.md` | `references/html-data-mapping.md`

# Step 5: Deploy - Interactive HTML Document

## MANDATORY EXECUTION RULES

- **ALWAYS** verify PRD exists before proceeding (`.ralph/prd-{module}.json`)
- **ALWAYS** pre-populate HTML with FEATURE_DATA + EMBEDDED_ARTIFACTS (no empty templates)
- **FEATURE_DATA.moduleSpecs** must have ONE entry per module (empty = BROKEN)
- **FEATURE_DATA.cadrage.scope** uses HTML keys (vital/important/optional/excluded)
- **ALWAYS** deploy SINGLE interactive HTML (multi-app or single-app per config)

## YOUR TASK

Deploy the single interactive HTML document pre-populated with all analysis data across all modules and applications. PRD and handoff data must already exist (generated by `/derive-prd`).

---

## EXECUTION SEQUENCE

### 1. Verify PRD Exists

For each module, verify PRD file exists:

```
FOR each module in modules:
  prdPath = ".ralph/prd-{moduleCode}.json"
  IF NOT exists(prdPath):
    BLOCKING ERROR: "PRD not found: {prdPath} — Run /derive-prd first"
    STOP
  IF fileSize(prdPath) < 100:
    BLOCKING ERROR: "PRD file too small: {prdPath} — Run /derive-prd to regenerate"
    STOP
```

Verify consolidation status:

```
IF workflow.mode === "project":
  projectFeature = ba-reader.findProjectFeature()
  FOR each app in projectFeature.applications:
    appFeature = ba-reader.findFeature(app.featureJsonPath)
    IF appFeature.status !== "consolidated":
      BLOCKING ERROR: "Application {app.code} not consolidated"
ELSE:
  feature = ba-reader.findFeature({feature_id})
  IF feature.status !== "consolidated":
    BLOCKING ERROR: "Feature status: {feature.status}, expected consolidated"
```

Display:
```
PRD verified: {module_count} modules
  .ralph/prd-{module1}.json ({size} bytes)
  .ralph/prd-{module2}.json ({size} bytes)
→ Proceeding to HTML generation...
```

---

### 2. Build FEATURE_DATA Object

Read from index.json (master module JSON files):

For EACH module:
- Read complete index.json for each module
- Map to FEATURE_DATA structure per `references/html-data-mapping.md`

**FEATURE_DATA structure:**
- metadata (analysisMode="interactive", workflowMode, versions, timestamps)
- cadrage (scope using HTML keys: vital/important/optional/excluded; objectives, constraints, assumptions)
- modules[] (all modules with all fields from index.json)
- moduleSpecs{} (one entry PER module with analysis, specification sections from index.json)
- consolidation (cross-module interactions)
- handoff (complexity, filesToCreate summary, totalFiles, totalTasks)

**Critical requirements:**
- moduleSpecs MUST have ONE entry per module (empty = BUG)
- cadrage.scope converts: mustHave->vital, shouldHave->important, couldHave->optional, outOfScope->excluded
- metadata.analysisMode from master.metadata.analysisMode (always "interactive")
- PROJECT MODE: include applications[], consolidation.crossApplicationInteractions

---

### 3. Build EMBEDDED_ARTIFACTS Object

Collect from FEATURE_DATA:
- **wireframes**: Per-module ASCII + SVG (if generated) — fields: format, content, svgContent
- **e2eFlows**: E2E diagrams from consolidated.e2eFlows
- **dependencyGraph**: From dependencyGraph section

**Field name mapping (CRITICAL):**
- wireframes use: `format`, `content`, `svgContent` (NOT mockupFormat/mockup)

---

### 4. Generate SVG Wireframes (Parallel, Optional)

> **After EMBEDDED_ARTIFACTS built but BEFORE HTML write.**
> This step is NEVER blocking — ASCII-only wireframes acceptable.
> **Reference:** Read `references/wireframe-svg-style-guide.md` for full agent prompt template

1. Collect all wireframes where `mockup` exists and `svgContent` is null
2. Spawn parallel Task(sonnet) agents — ONE per wireframe
3. Validate results: strip markdown fences, verify SVG syntax
4. Inject valid SVGs into `EMBEDDED_ARTIFACTS.wireframes[moduleCode][index].svgContent`
5. Display: "SVG wireframe generation: {successCount}/{total} generated, {failCount} fallback (ASCII)"

---

### 5. Replace Placeholders & Write HTML

1. Read HTML template from skill: `html/ba-interactive.html`
2. Serialize FEATURE_DATA and EMBEDDED_ARTIFACTS as JSON (2-space indent)
3. Replace 8 placeholders:
   - `{{FEATURE_DATA}}` — Full FEATURE_DATA JSON object
   - `{{EMBEDDED_ARTIFACTS}}` — Wireframes, E2E, dependency graph
   - `{{APPLICATION_NAME}}` — From master.metadata.application
   - Others per template

4. **Output path:**
   - Multi-app (project mode): `docs/business-analyse/v{version}/ba-interactive.html`
   - Single-app: `docs/{app}/business-analyse/v{version}/ba-interactive.html`

5. Write to file

---

### 6. Verify Deployment

**POST-CHECK (BLOCKING):**

1. **File size > 100KB** (indicates pre-populated)
   ```
   if [ $(stat --format=%s ba-interactive.html) -lt 100000 ]; then
     BLOCKING_ERROR("ba-interactive.html not pre-populated")
   fi
   ```

2. **moduleSpecs present in HTML** (must be serialized)
   ```
   if ! grep -q '"moduleSpecs"' ba-interactive.html; then
     BLOCKING_ERROR("moduleSpecs not found — FEATURE_DATA not serialized")
   fi
   ```

3. **cadrage.scope uses HTML keys** (vital/important/optional/excluded)
   ```
   if grep -q '"mustHave"' ba-interactive.html; then
     BLOCKING_ERROR("cadrage.scope still has JSON keys")
   fi
   ```

4. **Wireframe field names correct** (format/content, NOT mockupFormat/mockup)
   ```
   if grep -q '"mockupFormat"' ba-interactive.html; then
     BLOCKING_ERROR("Wireframes use 'mockupFormat' — must be 'format'")
   fi
   ```

5. **All modules have specs AND wireframes**
   ```
   FOR each module in FEATURE_DATA.modules:
     IF FEATURE_DATA.moduleSpecs[module.code] undefined:
       BLOCKING_ERROR("Module not in moduleSpecs")
     IF EMBEDDED_ARTIFACTS.wireframes[module.code] undefined:
       BLOCKING_ERROR("Module not in wireframes")
   ```

---

### 7. Display Completion Summary

```
══════════════════════════════════════════════════════════════
  [OK] HTML DEPLOY COMPLETE — {application_name}
══════════════════════════════════════════════════════════════

Modules: {count} ({names})

[DIR] Artifact generated:
  ba-interactive.html — Interactive document
     Path: {output_path}
     Pre-populated: {module_count} modules, {total_uc} use cases,
       {total_br} business rules, {total_wireframes} wireframes

[NEXT] Review & Validation:
  1. Open ba-interactive.html in browser
  2. Review all modules, use cases, business rules
  3. Validate wireframes and permissions
  4. If OK: /derive-prd then /ralph-loop to begin development
  5. If changes needed: /business-analyse to iterate

══════════════════════════════════════════════════════════════
```

---

## SELF-VERIFICATION (BEFORE COMPLETION)

1. `ba-interactive.html` exists and >100KB
2. FEATURE_DATA.moduleSpecs has entries for ALL modules
3. cadrage.scope uses HTML keys (vital/important/optional/excluded)
4. Wireframes use format/content fields (not mockupFormat/mockup)
5. POST-CHECK verification all passed

**IF any check fails -> generate missing artifact before completing.**

---

## NEXT STEP

Load: `steps/step-06-review.md`
