---
name: business-analyse
description: "Iterative multi-module business analysis with progressive context loading, JSON-first architecture, and interactive HTML deliverables."
model: opus
user_invocable: true
---

# /business-analyse — v2

## Architecture

**2 phases, 5 steps** — "Macro vers Specification"

### Phase 1 — Macro (Identification + Challenge)

| Step | File | Model | Role |
|------|------|-------|------|
| 00 | `step-00-init.md` | Sonnet | Detection new/update, scan existing, create index.json structure |
| 01 | `step-01-cadrage.md` | Opus | Context, stakeholders, scope, risks. ~40 core questions |
| 02 | `step-02-structure.md` | Opus | Identify App > Module > Section > Resource hierarchy, CHALLENGE each element |

### Phase 2 — Specification (Deep dive + Consolidation)

| Step | File | Model | Role |
|------|------|-------|------|
| 03 | `step-03-specify.md` | Opus | Deep dive per module: entities, BRs, UCs, permissions. Sequential internal loop |
| 04 | `step-04-consolidate.md` | Opus | Cross-module validation: data model, permission coherence, E2E flows |

### Development Paths — When to use what

SmartStack offers **two paths** from idea to code, depending on scope:

```
Path A — FAST (small module, < 5 min)          Path B — FULL (multi-module, hours/days)
═══════════════════════════════════════         ═══════════════════════════════════════

  "I want employees + absences"                  "Build a complete HR platform"
          │                                               │
          ▼                                               ▼
  ┌──────────────┐                               ┌──────────────────┐
  │   /sketch    │  0-2 questions                 │ /business-analyse│  ~40 questions
  │  (2 min)     │  Pure inference                │  (steps 00-04)   │  JSON output
  └──────┬───────┘                               └────────┬─────────┘
         │ Natural language prompt                        │ entities/rules/usecases.json
         ▼                                               ▼
  ┌──────────────┐                               ┌──────────────────┐
  │    /apex     │  1 module                      │  /business-analyse-design   │  screens/wireframes
  │  (30-60 min) │  APEXE methodology             │                  │  navigation tree
  └──────────────┘                               └────────┬─────────┘
                                                          │ screens.json, navigation.json
                                                          ▼
                                                 ┌──────────────────┐
                                                 │/business-analyse-html│  Interactive HTML
                                                 │                  │  for client review
                                                 └────────┬─────────┘
                                                          │ ba-interactive.html
                                                          ▼
                                                 ┌──────────────────┐
                                                 │/business-analyse-review│◄── ba-review.json
                                                 │  Corrections?    │    (exported from HTML)
                                                 └───┬─────────┬───┘
                                              YES    │         │ NO (approved)
                                         ┌───────────┘         └──────────┐
                                         ▼                                ▼
                                  Back to Phase 1             ┌────────────────────────┐
                                  or Phase 2                  │/business-analyse-     │  PRD + handoff
                                  (depends on scope)          │      handoff           │
                                                              └────────┬───────────────┘
                                                                       │ .ralph/prd-*.json
                                                                       ▼
                                                              ┌──────────────────┐
                                                              │   /business-analyse-develop    │  Orchestrator
                                                              │  (iterative)     │  delegates to ▼
                                                              └────────┬─────────┘
                                                                       │ /apex -d per module
                                                                       ▼
                                                              ┌──────────────────┐
                                                              │    /apex -d      │  Code generation
                                                              │  (per module)    │  5 layers
                                                              └──────────────────┘
```

### Data flow between skills

| From | To | Data | Format |
|------|----|------|--------|
| `/sketch` | `/apex` | Inferred design (entities, FK, labels, code patterns) | Natural language prompt |
| `/business-analyse` | `/business-analyse-design` | Entities, use cases, permissions | JSON (`entities.json`, `usecases.json`, `permissions.json`) |
| `/business-analyse-design` | `/business-analyse-html` | Screen specs, wireframes, navigation | JSON (`screens.json`, `navigation.json`) |
| `/business-analyse-html` | Client | Interactive review document | HTML (`ba-interactive.html`) |
| Client | `/business-analyse-review` | Corrections | JSON (`ba-review.json`, exported from HTML) |
| `/business-analyse-review` | `/business-analyse` or `/business-analyse-design` | Corrections applied, new version | JSON (updated thematic files) |
| `/business-analyse` (approved) | `/business-analyse-handoff` | Consolidated BA data | JSON (all `index.json` + thematic files) |
| `/business-analyse-handoff` | `/business-analyse-develop` | Handoff data + PRD | JSON (`.ralph/prd-*.json`, `handoff.json`) |
| `/business-analyse-develop` | `/apex -d` | Module context + PRD | JSON (`.ralph/prd-{module}.json`) |

### /business-analyse-review correction routing

| Correction scope | Route to | Reason |
|------------------|----------|--------|
| Entities, rules, UCs, permissions | `/business-analyse` step-03 | Re-specify affected modules |
| Screens, wireframes, navigation | `/business-analyse-design` | Re-design UI |
| Both analysis + UI | `/business-analyse` step-03, then `/business-analyse-design` | Full re-spec |
| Cadrage/scope only | `/business-analyse-html` | Just regenerate HTML |
| No corrections (approved) | `/business-analyse-handoff` | Proceed to code generation |

> **Rule:** Path A (`/sketch` → `/apex`) is for quick, single-module additions. Path B (full cycle) is for multi-module projects or when the client needs a formal review process.
> **PRD generation:** Handoff data and PRD files are generated by the `/business-analyse-handoff` skill.

## JSON Architecture — Granular files + Index

Each module is split into thematic JSON files with an `index.json` that references them:

```
docs/{app}/{module}/business-analyse/v1.0/
  index.json              ← Index with metadata + file references
  cadrage.json            ← Context, stakeholders, scope, risks (if app-level)
  entities.json           ← Entities, attributes, relations
  rules.json              ← Business rules (BRs)
  usecases.json           ← Use cases (UCs)
  permissions.json        ← Permissions, roles, access matrix
  screens.json            ← Interface specs (produced by /business-analyse-design)
  validation.json         ← Validation results, checks
  handoff.json            ← File mapping, APIs, handoff data
```

### File hierarchy

```
docs/
  business-analyse/v1.0/
    index.json                    ← Project index (multi-app)
    cadrage.json                  ← Project-level framing
  {app}/
    business-analyse/v1.0/
      index.json                  ← Application index
      cadrage.json                ← Application framing
    {module}/
      business-analyse/v1.0/
        index.json                ← Module index
        entities.json, rules.json, usecases.json, ...
  ba-interactive.html             ← Single unified HTML
```

### Partial loading

Each step loads only the files it needs via `index.json`:
- Step 03 (specify): loads `index.json` + `entities.json` for current module only
- Step 04 (consolidate): loads all `index.json` files for summary counts

## Workflow Modes

| Mode | Condition | Behavior |
|------|-----------|----------|
| `new` | No existing index.json | Full analysis from step 00 |
| `update` | Existing index.json found | Delta analysis, skip completed sections |

## Context Loading Rules

Each step loads ONLY what it needs:

| Step | Always loaded | Conditionally loaded |
|------|---------------|---------------------|
| 00 | `_shared.md` | — |
| 01 | `_shared.md`, `step-01-cadrage.md` | questionnaires |
| 02 | `_shared.md`, `step-02-structure.md` | cadrage.json from step 01 |
| 03 | `_shared.md`, `step-03-specify.md` | current module's index.json + relevant files |
| 04 | `_shared.md`, `step-04-consolidate.md` | all module index.json files |

## Agents

| Agent | Role | Operations |
|-------|------|------------|
| `ba-writer` | Write granular JSON files | create, enrichSection, updateIndex, createVersion, applyReview |
| `ba-reader` | Read via index.json | findFeature, readSection, getModuleStatus, getSummaryForSkill |

## HTML Output

HTML generation is handled by the `/business-analyse-html` skill. After step-04, invoke `/business-analyse-html` to produce the interactive HTML document. For client review corrections, use `/business-analyse-review`.

## Step Execution

```
STEP 00 (init)
  → Load: _shared.md
  → Execute: step-00-init.md
  → Output: index.json structure, workflow mode detected

STEP 01 (cadrage)
  → Load: _shared.md, step-01-cadrage.md, questionnaires
  → Execute: Interactive Q&A with client (~40 questions)
  → Output: cadrage.json (context, stakeholders, scope, risks, criteria)

STEP 02 (structure)
  → Load: _shared.md, step-02-structure.md, cadrage.json
  → Execute: Identify App > Module > Section > Resource hierarchy
  → Challenge: Question each element's necessity
  → Output: modules[], applications[], anticipatedSections per module

STEP 03 (specify) — SEQUENTIAL MODULE LOOP
  → For each module (in dependency order):
    → Load: _shared.md, step-03-specify.md, module index.json
    → Execute: entities, BRs, UCs, permissions
    → Output: entities.json, rules.json, usecases.json, permissions.json
  → No team mode — sequential ensures 100% context per module

STEP 04 (consolidate) — FINAL BA STEP
  → Load: _shared.md, step-04-consolidate.md, all index.json
  → Execute: Data model validation, permission coherence, E2E flows
  → Output: validation.json, consolidated data
  → Next: invoke /business-analyse-design (Phase 2), then /business-analyse-html, then /business-analyse-review for client cycle
```

## References

| File | Content |
|------|---------|
| `/business-analyse-html` skill | HTML generation (FEATURE_DATA mapping, build, render, verify) |
| `/business-analyse-review` skill | Apply client corrections from ba-review.json |
| `references/naming-conventions.md` | SmartStack naming rules |
| `references/validation-checklist.md` | Validation criteria checklist |
| `references/acceptance-criteria.md` | Acceptance criteria patterns |

> **Cross-reference:** Handoff data, PRD generation, file templates, and BR-to-code mappings are in the `/business-analyse-handoff` skill.

## Questionnaires

| File | Questions | Focus |
|------|-----------|-------|
| `questionnaire/01-context.md` | 3 | Business process, friction points, vision |
| `questionnaire/02-stakeholders-scope.md` | 10 | User profiles, access levels, scope boundaries |
| `questionnaire/03-data-ui.md` | ~15 | Data entities, UI expectations, dashboards |
| `questionnaire/04-risks-metrics.md` | — | NOT USED (risks/metrics out of BA scope) |
| `questionnaire/05-cross-module.md` | ~8 | Cross-module dependencies, integration impact |

## Entry Point

**FIRST ACTION:** Load `steps/step-00-init.md`
