# Business Analysis — Shared Conventions

## JSON-First Architecture

Feature data is stored as granular JSON files, NOT markdown. Each module has an `index.json` referencing thematic files.

### File structure

```
docs/
  {projet-slug}/                     ← Project (kebab-case, 100% autonomous)
    v{X.Y}/
      index.json                     ← Project master index
      cadrage.json                   ← Project-level framing
      consolidation.json             ← Cross-module validation
      navigation.json                ← Navigation tree
      validation.json                ← Validation results
      ba-interactive.html            ← Generated HTML deliverable
      {app-kebab}/                   ← Application (kebab-case)
        index.json                   ← Application index
        {module-kebab}/              ← Module (kebab-case)
          index.json                 ← Module index
          entities.json              ← Entities, attributes, relations
          rules.json                 ← Business rules
          usecases.json              ← Use cases
          permissions.json           ← Permissions matrix
          screens.json               ← Interface specs (sections, resources, mockups)
          handoff.json               ← File mapping, API specs
```

### Index.json structure

```json
{
  "metadata": {
    "featureId": "FEAT-001",
    "moduleCode": "Employees",
    "applicationCode": "HumanResources",
    "version": "1.0",
    "status": "specified",
    "createdAt": "...",
    "lastModified": "..."
  },
  "files": {
    "entities": { "path": "entities.json", "hash": "abc123", "lastModified": "..." },
    "rules": { "path": "rules.json", "hash": "def456", "lastModified": "..." },
    ...
  },
  "summary": {
    "entityCount": 3,
    "ruleCount": 5,
    "useCaseCount": 8,
    "permissionCount": 22,
    "screenCount": 4,
    "dependencies": ["Absences"]
  }
}
```

### Partial loading

Steps load only the files they need:
- **ba-reader** reads `index.json` to discover files, then loads only the requested file
- **ba-writer** writes to specific files (e.g., `entities.json`) and updates the hash in `index.json`

## Workflow Modes

| Mode | Trigger | Description |
|------|---------|-------------|
| `new` | No existing index.json | Full analysis from scratch |
| `update` | Existing index.json found | Delta analysis (add modules, update specs) |

### Workflow detection

```
1. Check for existing docs/*/v*/index.json → mode = "update"
2. Otherwise → mode = "new"
```

> **Legacy detection:** Also check `docs/business-analyse/v*/index.json` and `docs/*/business-analyse/v*/index.json` for backward compatibility with pre-ba-006 projects.

> **Note:** Review mode (`ba-review.json`) is handled by the `/business-analyse-review` skill.

## Navigation Hierarchy

Maps to SmartStack DB tables:

| Level | DB Table | Example |
|-------|----------|---------|
| Application | nav_Applications | HumanResources |
| Module | nav_Modules | Employees |
| Section | nav_Sections | list, detail |
| Resource | nav_Resources | employees-grid, employee-form |

### Naming conventions

- **Project directory**: kebab-case slug (e.g., `projet-rh`, `commande-repas`)
- **Application directory**: kebab-case (e.g., `human-resources`) — derived from PascalCase code via `toKebabCase()`
- **Module directory**: kebab-case (e.g., `employees`) — derived from PascalCase code via `toKebabCase()`
- **Application code** (in JSON): PascalCase (e.g., `HumanResources`)
- **Module code** (in JSON): PascalCase (e.g., `Employees`)
- **Section code**: kebab-case (e.g., `list`, `detail`, `dashboard`)
- **Resource code**: kebab-case (e.g., `employees-grid`, `employee-form`)

### Directory name conversion

```javascript
function toKebabCase(code) {
  return code
    .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
    .replace(/([A-Z]+)([A-Z][a-z])/g, '$1-$2')
    .toLowerCase();
}
```

### Project detection and selection

Projects are discovered by glob — no central registry:

```
1. Glob: docs/*/v*/index.json
2. If 0 projects → ERROR "No project found. Run /business-analyse first."
3. If 1 project → auto-select
4. If N projects → AskUserQuestion "Which project?"
   Options: [{label: "{slug} (v{X.Y})", description: "{appCount} apps, {moduleCount} modules, status: {status}"}, ...]
5. Store selection in .business-analyse/config.json
```

### Path resolution helpers

```javascript
function resolveProjectDir(projectSlug, version) {
  return `docs/${projectSlug}/v${version}`;
}

function resolveAppDir(projectDir, appCode) {
  return `${projectDir}/${toKebabCase(appCode)}`;
}

function resolveModuleDir(projectDir, appCode, moduleCode) {
  return `${projectDir}/${toKebabCase(appCode)}/${toKebabCase(moduleCode)}`;
}
```

## Permission Paths

Format: `{ApplicationCode}.{ModuleCode}.{Action}`

Actions: `Read`, `Create`, `Update`, `Delete`, `Export`, `Validate`

Example: `HumanResources.Employees.Read`

For section-level: `{ApplicationCode}.{ModuleCode}.{SectionCode}.{Action}`

## Agents

### ba-writer

Writes granular JSON files. Key operations:
- `create(scope, data)` — Create index.json + initial files in `docs/{projectSlug}/v{X.Y}/`
- `enrichSection(fileType, data)` — Write to specific file (entities.json, rules.json, etc.)
- `updateIndex(summary)` — Update index.json metadata and summary
- `createVersion(type)` — Create new version (major/minor)
- `applyReview(reviewData)` — Apply ba-review.json corrections

All paths follow the pattern: `docs/{projectSlug}/v{X.Y}/{appKebab}/{moduleKebab}/`

### ba-reader

Reads via index.json. Key operations:
- `findFeature(featureId)` — Locate feature by ID
- `readSection(moduleCode, fileType)` — Read specific file via index
- `getModuleStatus()` — Status table of all modules
- `getCompletedModulesSummary()` — Compact summaries for context loading
- `getSummaryForSkill(skill)` — Context for other skills (business-analyse-develop, etc.)

## Status Progression

```
draft → framed → decomposed → specified → consolidated → designed → reviewed → handed-off
```

| Status | Set by | Meaning |
|--------|--------|---------|
| draft | Step 00 | Feature created, no content |
| framed | Step 01 | Application-level framing complete (scope, stakeholders, roles) |
| decomposed | Step 02 | Module hierarchy identified (App > Module > Section > Resource) |
| specified | Step 03 | Module fully specified (entities, UCs, BRs, permissions, screens) |
| consolidated | Step 04 | Cross-module validation and consolidation passed |
| designed | Step 05 | UI/UX design and navigation complete |
| reviewed | `/business-analyse-review` | Client review applied |
| handed-off | `/business-analyse-handoff` | PRD files generated, ready for development |

## Handoff & PRD Generation

Handoff data and PRD files are generated by the `/business-analyse-handoff` skill. The workflow is:

```
/business-analyse (steps 00-04) → /business-analyse-html → /business-analyse-review (if needed) → /business-analyse-handoff → /business-analyse-develop
```

## HTML Generation

For HTML generation, use the `/business-analyse-html` skill after step-04 consolidation. For client review corrections, use `/business-analyse-review`.

## Resume Protocol

State is tracked in `index.json` metadata:
- `metadata.status` — Current status
- `metadata.lastModified` — Last modification timestamp

The step system checks metadata to determine where to resume.
