---
name: step-03-specify
description: Sequential deep dive per module - entities, BRs, UCs, permissions
model: opus
next_step: steps/step-04-consolidate.md
---

# Step 03 — Specify (Deep Dive per Module)

## Objective

For each module (in dependency order), produce complete specifications: entities, business rules, use cases, and permissions. Interface specs (screens, wireframes, navigation) are handled by Phase 2 (`/ba-design-ui`).

## Prerequisites

- Step 02 (structure) completed
- Applications, modules, sections, dependencies identified

## Sequential Execution

**No team mode.** Each module receives 100% of LLM attention for maximum specification quality.

Process modules in topological order (dependencies first):
```
For module in topologicalSort(modules):
    specify(module)
```

## Per-Module Specification Loop

For each module, execute these sub-steps:

### A. Context Loading

Load via ba-reader:
- Module's `index.json` (if exists from previous run)
- Application `cadrage.json` for stakeholder context
- Completed modules' summaries (compact, <100 lines each)

### B. Entities

For each entity identified in step 02:

```json
{
  "name": "Employee",
  "description": "Represente un employe de l'entreprise",
  "attributes": [
    { "name": "code", "type": "string", "required": true, "description": "Identifiant unique" },
    { "name": "userId", "type": "guid", "required": true, "description": "Reference vers l'utilisateur" },
    { "name": "departmentId", "type": "guid", "required": true, "description": "Departement d'affectation" },
    { "name": "hireDate", "type": "date", "required": true, "description": "Date d'embauche" },
    { "name": "position", "type": "string", "description": "Poste occupe" },
    { "name": "status", "type": "enum", "options": ["Active", "Inactive", "OnLeave", "Terminated"], "description": "Statut de l'employe" }
  ],
  "relationships": [
    { "target": "Department", "type": "ManyToOne", "description": "Appartient a un departement" },
    { "target": "Contract", "type": "OneToMany", "description": "Possede plusieurs contrats" }
  ]
}
```

### C. Business Rules

For each entity/process, identify rules:

```json
{
  "id": "BR-VAL-EMPLOYEES-001",
  "name": "Validation date embauche",
  "category": "validation",
  "statement": "La date d'embauche ne peut pas etre dans le futur",
  "example": "Date embauche = 2027-01-01 → erreur car > date du jour",
  "entities": ["Employee"],
  "severity": "blocking"
}
```

Categories: `validation`, `calculation`, `workflow`, `security`, `data`

### D. Use Cases

For each stakeholder action:

```json
{
  "id": "UC-EMPLOYEES-001",
  "name": "Creer un employe",
  "actor": "Responsable RH",
  "preconditions": ["L'utilisateur a la permission HumanResources.Employees.Create"],
  "steps": [
    "L'utilisateur ouvre la page de creation",
    "Il remplit les champs obligatoires (nom, departement, date embauche)",
    "Il valide le formulaire",
    "Le systeme verifie les regles metier (BR-VAL-EMPLOYEES-001)",
    "Le systeme cree l'employe et affiche la fiche"
  ],
  "alternative": "Si les donnees sont invalides, le systeme affiche les erreurs",
  "businessRules": ["BR-VAL-EMPLOYEES-001"],
  "result": "L'employe est cree avec le statut 'Actif'"
}
```

### E. Permissions

Define the permission matrix:

```json
{
  "roles": ["RH Admin", "Manager", "Employee"],
  "matrix": [
    { "role": "RH Admin", "permissions": ["Read", "Create", "Update", "Delete", "Export"] },
    { "role": "Manager", "permissions": ["Read", "Export"] },
    { "role": "Employee", "permissions": ["Read"] }
  ],
  "permissionPaths": [
    "HumanResources.Employees.Read",
    "HumanResources.Employees.Create",
    "HumanResources.Employees.Update",
    "HumanResources.Employees.Delete",
    "HumanResources.Employees.Export"
  ]
}
```

**Auto-detection rules:**
- If the cadrage mentions "export", "Excel", "CSV", or "télécharger" → automatically add `.export` permission and an export use case (UC-{PREFIX}-EXPORT)
- If the cadrage mentions "import", "importer", "upload" → automatically add `.import` permission and an import use case (UC-{PREFIX}-IMPORT)

### F. Interface Specs — Delegated to /ba-design-ui

> **Screen specifications are NOT produced in this step.**
> Interface design (SmartTable columns, SmartForm fields, wireframes, navigation) is handled by Phase 2: `/ba-design-ui`.
> This separation allows iterating on UI design without replaying the full analysis cycle.

### G. Write & Advance

After completing all sub-steps for a module:

1. Write via ba-writer:
   - `entities.json`
   - `rules.json`
   - `usecases.json`
   - `permissions.json`
   - Update `index.json` (hashes, summary counts)

2. Update module status to `specified`

3. Advance to next module in topological order

### H. Module Completion Check

After all modules are specified:
- Verify all modules have status `specified`
- Display summary: total entities, rules, UCs, permissions across all modules
- Remind user: "Run /ba-design-ui to design interfaces for these modules"
- Transition to step 04

## POST-CHECK

Before advancing to step 04, verify:
- [ ] Every module has at least 1 entity
- [ ] Every module has at least 1 use case
- [ ] Every module has at least 1 business rule
- [ ] Every module has permissions defined
- [ ] Entity attributes have `type` defined (string, int, date, enum, guid, etc.)
- [ ] All entity relationships reference existing entities
- [ ] All UC business rule references exist
- [ ] All permission paths follow the convention
- [ ] Sections with `sectionType: view` do NOT appear in `permissionPaths` (they inherit from module)
- [ ] Sections with `permissionMode: read-only` only have `.read` in `permissionPaths` (no create/update/delete)
- [ ] Sections with `permissionMode: inherit` have ZERO entries in `permissionPaths`

## Transition

→ Step 04 (consolidate) — Cross-module validation
