---
name: step-03-specify
description: Sequential deep dive per module - entities, BRs, UCs, permissions, screens
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, permissions, and interface specs (screens).

## 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"
  ]
}
```

### F. Interface Specs (Screens)

For each section/resource identified in step 02, specify the full interface:

```json
{
  "sectionCode": "list",
  "sectionLabel": "Liste des employes",
  "resources": [
    {
      "code": "employees-grid",
      "type": "SmartTable",
      "label": "Grille des employes",
      "columns": [
        { "field": "code", "label": "Code", "type": "text", "sortable": true },
        { "field": "fullName", "label": "Nom complet", "type": "text", "sortable": true },
        { "field": "department.name", "label": "Departement", "type": "lookup", "filterable": true },
        { "field": "status", "label": "Statut", "type": "badge", "filterable": true }
      ],
      "actions": ["create", "edit", "delete", "export"],
      "filters": ["department", "status"],
      "permission": "HumanResources.Employees.Read"
    }
  ]
}
```

Resource types:
- **SmartTable**: columns[], actions[], filters[], permission
- **SmartForm**: tabs[{ label, fields[{ field, label, type, required, readonly, options }] }], actions[], permission
- **SmartCard**: columns/fields[], permission
- **SmartKanban**: options/columns[], permission
- **SmartDashboard**: kpis[{ label, value }], permission
- **SmartFilter**: options[], permission

### G. Write & Advance

After completing all sub-steps for a module:

1. Write via ba-writer:
   - `entities.json`
   - `rules.json`
   - `usecases.json`
   - `permissions.json`
   - `screens.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, screens across all 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
- [ ] Every module has at least 1 screen defined
- [ ] All entity relationships reference existing entities
- [ ] All UC business rule references exist
- [ ] All permission paths follow the convention

## Transition

→ Step 04 (consolidate) — Cross-module validation
