# Deploy Mode Support & Troubleshooting

> Reference for `/business-analyse-html` skill (HTML deployment) and `/business-analyse-handoff` skill (handoff + PRD generation) — mode variations and common issues.

## Mode Support

### Standard Mode

Full handoff with all implementation details (via `/business-analyse-handoff`):
- All 8 file categories (including documentation)
- Complete BR-to-code mapping
- Full API endpoint summary
- Detailed prd.json
- Comprehensive progress tracker

### Micro Mode (use_case = micro)

Simplified handoff with minimal scope:
- Only essential CRUD entity + controller
- 3 core SeedData entries (omit some optional ones)
- Basic prd.json with simplified sections
- Lightweight progress.txt
- Display `/business-analyse-develop` command for later use

### Delta Mode (use_case = refactoring)

Focused handoff for changes:
- Only affected modules listed
- Reuse existing implementation patterns
- Highlight what changed vs baseline
- Update only affected prd.json sections
- Progress tracker shows only delta tasks

### Multi-Application Mode (workflow.mode = "project")

Full handoff across multiple applications within a project:

**Artifacts generated:**
- Per-module: `.ralph/prd-{moduleCode}.json` (one per module across all applications)
- Per-application cross-module: `.ralph/prd-CrossModule-{appCode}.json` (if app has 2+ modules)
- Cross-application: `.ralph/prd-CrossApplication.json` (integration tests between applications)
- Progress tracker: `.ralph/progress.txt` (grouped by application, then by module)
- BA manifest: `docs/index.json` (project-level entry + per-application + per-module entries)
- Interactive HTML: one HTML file per application at `docs/{app}/business-analyse/v{version}/ba-interactive.html`

**Project-level manifest entry:**
```json
{
  "scope": "project",
  "projectId": "PROJ-001",
  "projectName": "HR Platform",
  "version": "1.0",
  "status": "handed-off",
  "applications": ["HumanResources", "EmployeeSelfService"],
  "path": "business-analyse/v1.0/index.json",
  "updatedAt": "2026-02-16T..."
}
```

**Progress tracker structure (multi-app):**
```
# Progress Tracker — {projectName}

## Application: {app1Name} ({app1Context})

### Module: {module1} (Layer 0 — simple)
- [ ] Domain: Entity1.cs
- [ ] Application: Entity1Service.cs
...

### Module: {module2} (Layer 1 — medium)
...

## Application: {app2Name} ({app2Context})
...

## Cross-Application Integration
- [ ] SharedEntityValidationTests.cs
- [ ] CrossAppPermissionTests.cs
- [ ] CrossAppE2EFlowTests.cs

## Summary
| Application | Modules | Files | Tasks | Complexity |
|-------------|---------|-------|-------|------------|
| {app1}      | {n}     | {n}   | {n}   | {level}    |
| {app2}      | {n}     | {n}   | {n}   | {level}    |
| Cross-App   | —       | 3     | 3     | —          |
| **Total**   | {n}     | {n}   | {n}   | {global}   |
```

**seedDataCore differences:**
- `navigationApplications[]` has one entry per application
- `navigationModules[]` includes `applicationCode` field for each module
- `permissions[]` use per-application prefixes (e.g., `hr.*` vs `admin.*`)
- `rolePermissions[]` are scoped per application (same role can have different permissions per app)
- Seed data order: applications in topological order, then modules within each application

**business-analyse-develop execution (recommended):**
- Run `/business-analyse-develop` once per application (module-by-module within each app)
- Cross-application PRD runs last after all applications are implemented
- Application order follows `applicationDependencyGraph.topologicalOrder`

## Troubleshooting

| Issue | Resolution |
|-------|-----------|
| All modules missing handoff data | Run `/business-analyse-handoff` skill. Handoff MUST be written to each module's handoff.json. |
| prd.json generation failed | Run `/business-analyse-handoff`. Verify ss business-analyse-handoff command is installed and index.json path is correct. |
| progress.txt incomplete | Ensure all CORE SeedData entries are present: 2 app-level (NavigationApplication + ApplicationRoles) + per module (NavigationModule + NavigationSections + Permissions + Roles). Check topological order. |
| BA manifest not found | Create docs/index.json if missing. Use schema provided in section 3. |
| Manifest entries incorrect | Verify appCode, moduleCode, and version match index.json metadata exactly. |
| ba-interactive.html is too small (< 100KB) | FEATURE_DATA not serialized correctly. Verify JSON structure. Re-run FEATURE_DATA build. |
| moduleSpecs missing from HTML | FEATURE_DATA.moduleSpecs is empty or not included in JSON. Verify each module is iterated and populated. |
| Scope keys still show "inScope" instead of "inscope" | Conversion from JSON keys to HTML keys failed. Check cadrage.scope conversion logic. |
| Wireframes array is empty | Verify each module has screens.json with wireframe data (Format A: screens[].mockup, Format B: sections[].wireframe). If missing, step-02 will auto-generate text descriptions from columns/tabs. |
| Mockups show ASCII instead of HTML tables | screens[] in moduleSpecs has empty resources. Verify screens.json format was normalized correctly (Format A: screens[] or Format B: sections[]) by step-02. |
| dependencyGraph missing | Verify master index.json has consolidation.dependencyGraph. If missing, create empty nodes/edges arrays. |
| HTML opens but data blank (localStorage issue) | Clear browser localStorage. HTML will load pre-populated FEATURE_DATA on first load. |
| Export/re-import fails | Verify exported JSON matches original schema. Validate with `/business-analyse -x --validate`. |
