# 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/
  business-analyse/v{X.Y}/
    index.json           ← Project index (multi-app only)
    cadrage.json         ← Project-level framing
  {app}/
    business-analyse/v{X.Y}/
      index.json         ← Application index
      cadrage.json       ← App-level framing
    {module}/
      business-analyse/v{X.Y}/
        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)
        validation.json  ← Validation results
        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/**/index.json → mode = "update"
2. Otherwise → mode = "new"
```

> **Note:** Review mode (`ba-review.json`) is handled by the `/ba-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

- **Application code**: PascalCase (e.g., `HumanResources`)
- **Module code**: PascalCase (e.g., `Employees`)
- **Section code**: kebab-case (e.g., `list`, `detail`, `dashboard`)
- **Resource code**: kebab-case (e.g., `employees-grid`, `employee-form`)

## 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
- `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

### 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 (ralph-loop, etc.)

## Status Progression

```
draft → identified → specified → validated → reviewed
```

| Status | Set by | Meaning |
|--------|--------|---------|
| draft | Step 00 | Feature created, no content |
| identified | Step 02 | Hierarchy identified (App > Module > Section > Resource) |
| specified | Step 03 | Module fully specified (entities, UCs, BRs, permissions, screens) |
| validated | Step 04 | Cross-module validation passed |
| reviewed | `/ba-review` | Client review applied |

## Handoff & PRD Generation

Handoff data and PRD files are generated by the `/derive-prd` skill. The workflow is:

```
/business-analyse (steps 00-04) → /ba-generate-html → /ba-review (if needed) → /derive-prd → /ralph-loop
```

## HTML Generation

For HTML generation, use the `/ba-generate-html` skill after step-04 consolidation. For client review corrections, use `/ba-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.
