@atlashub/smartstack-cli 2.3.0 → 2.5.0

package/templates/skills/business-analyse/steps/step-02-specify.md

@@ -1,899 +0,0 @@
-# Step 02: Specification
-
-> **Version:** 3.0.0
-> **Name:** step-02-specify
-> **Next step:** steps/step-03-validate.md
-> **Purpose:** Enrich feature.json with detailed specification section (use cases, functional requirements, actors, permissions, wireframes, scenarios)
-> **Input:** feature.json (scope, analysis sections populated)
-> **Output:** feature.json.specification enriched + status: "specified"
-
----
-
-## 1. Introduction
-
-This step transforms the analysis from **discovery** into detailed **specifications**. You will:
-
-1. **Define actors and permissions** - Map stakeholder roles to system actors and RBAC permissions
-2. **Create use cases** - Model user interactions with UC-XXX identifiers
-3. **Define functional requirements** - Specify what the system must do (FR-XXX format)
-4. **Design permission matrix** - Map actors × resources × operations
-5. **Plan navigation & SeedData** - Design UI hierarchy and mandatory reference data
-6. **Sketch UI wireframes** - Visual representation of key screens
-7. **Write Gherkin scenarios** - Acceptance criteria in BDD format
-8. **Define validations & messages** - Business rules for data quality
-9. **Model data lifecycle** - Creation, updates, deletions, archiving patterns
-
----
-
-## 2. Mode Support
-
-### Standard Mode
-Execute all sections in full detail.
-
-### Delta Mode
-IF use_case = refactoring:
-- Only add/modify use cases, functional requirements, and permissions for **affected features**
-- Keep existing UCs, FRs, and permissions intact (DO NOT regenerate complete matrix)
-- Mark affected sections with `delta: true` in specification
-- Preserve backwards compatibility
-
-### Micro Mode
-IF use_case = micro:
-- Generate **minimal spec** for MVP
-- Use cases: 1-2 only (typically Create + Read, or List + Detail)
-- Functional requirements: standard CRUD only (no advanced features)
-- Permission matrix: default 4-role (Admin, Manager, User, Guest)
-- Gherkin scenarios: basic happy path + one error case
-- No navigation hierarchy complexity
-- Minimal SeedData (only essential lookups)
-
----
-
-## 3. Section 1: Define Actors & Permissions
-
-### 3.1 Map Stakeholder Roles to System Actors
-
-From `feature.json.discovery.stakeholders[]`, create an **actors** section in specification:
-
-```json
-{
-  "specification": {
-    "actors": [
-      {
-        "id": "ACTOR-001",
-        "role": "Admin",
-        "description": "System administrator with full control",
-        "canDelegate": true,
-        "basePermissions": ["Read", "Create", "Update", "Delete"]
-      },
-      {
-        "id": "ACTOR-002",
-        "role": "Manager",
-        "description": "Module manager with approval authority",
-        "canDelegate": false,
-        "basePermissions": ["Read", "Create", "Update"]
-      },
-      {
-        "id": "ACTOR-003",
-        "role": "User",
-        "description": "Standard user for daily operations",
-        "canDelegate": false,
-        "basePermissions": ["Read", "Create"]
-      },
-      {
-        "id": "ACTOR-004",
-        "role": "Guest",
-        "description": "External user with minimal access",
-        "canDelegate": false,
-        "basePermissions": ["Read"]
-      }
-    ]
-  }
-}
-```
-
-### 3.2 Define Permission Categories
-
-For each actor, enumerate:
-
-| Category | Examples | Notes |
-|----------|----------|-------|
-| **Read** | View list, View detail, Search, Export | Includes all retrieval operations |
-| **Create** | Add new record, Bulk import | Creation with initial state |
-| **Update** | Edit fields, Change status, Reassign | Update including state transitions |
-| **Delete** | Hard delete, Soft delete/Archive | Deletion or data removal |
-| **Approve** | Approve changes, Reject submissions | Workflow decisions |
-| **Delegate** | Assign task to another user | Transfer responsibility |
-| **Execute** | Trigger workflow, Process batch | Special actions |
-
----
-
-## 4. Section 2: Create Use Cases (UC-XXX)
-
-### 4.1 Format & Structure
-
-For each major user interaction, create a use case:
-
-```markdown
-### UC-001: List [Resource] by [Criteria]
-
-| Field | Value |
-|-------|-------|
-| **ID** | UC-001 |
-| **Title** | List [Module] by [Criteria] |
-| **Actor(s)** | User, Manager |
-| **Trigger** | User navigates to [Module] menu |
-| **Precondition** | User is authenticated and has Read permission |
-| **Main Flow** | 1. System loads records from database filtered by [criteria] \| 2. Display paginated results with [fields] \| 3. User can sort/filter further |
-| **Alternative Flow** | No records: Show empty state with message; User cancels: Return to previous screen |
-| **Postcondition** | List displayed; User can select record for detail view |
-| **Linked Rules** | BR-001, BR-003 |
-
-```
-
-### 4.2 Use Case Categories
-
-Organize around resource operations:
-
-| UC Type | Examples | Count |
-|---------|----------|-------|
-| **List/Search** | List Orders, Search Customers, Find Products | 1 per resource |
-| **Create** | Create Order, Add Customer, Register Employee | 1 per resource |
-| **Read Detail** | View Order details, Customer profile | 1 per resource |
-| **Update** | Edit Order, Modify Customer address | 1 per resource |
-| **Delete/Archive** | Cancel Order, Archive Customer | 0-1 per resource |
-| **Bulk Operations** | Bulk Import Orders, Export Customers | 0-1 per resource |
-| **Workflow** | Approve Order, Escalate Ticket | 1 per workflow |
-| **Reports** | Order Summary, Customer Analysis | 0-1 per module |
-
-**Micro mode:** Limit to UC-001 (List) and UC-002 (Create), or UC-001 (List) and UC-002 (Detail).
-
-### 4.3 Link to Business Rules
-
-Each UC's "Linked Rules" field references `analysis.businessRules[].id`:
-
-```json
-{
-  "useCases": [
-    {
-      "id": "UC-001",
-      "linkedRules": ["BR-001", "BR-003"]
-    }
-  ]
-}
-```
-
----
-
-## 5. Section 3: Define Functional Requirements (FR-XXX)
-
-### 5.1 Format & Priorities
-
-For each capability, create an FR:
-
-```json
-{
-  "functionalRequirements": [
-    {
-      "id": "FR-001",
-      "title": "Display [Resource] List",
-      "description": "System shall display paginated list of [resources] with sortable/filterable columns",
-      "priority": "MUST",
-      "actor": "User",
-      "linkedRules": ["BR-001"],
-      "acceptance": [
-        "List loads within 2 seconds",
-        "Pagination supports 10/25/50 items per page",
-        "User can sort by any column",
-        "User can filter by [field1], [field2]"
-      ]
-    },
-    {
-      "id": "FR-002",
-      "title": "Create [Resource] with Validation",
-      "description": "System shall accept new [resource] creation with mandatory field validation",
-      "priority": "MUST",
-      "actor": "User",
-      "linkedRules": ["BR-002", "BR-003"],
-      "acceptance": [
-        "All mandatory fields enforced on form",
-        "Validation messages appear inline",
-        "Submit button disabled until valid",
-        "Success message on creation"
-      ]
-    }
-  ]
-}
-```
-
-### 5.2 Priority Mapping
-
-| Priority | MOSCOW | Impact | Scheduling |
-|----------|--------|--------|-----------|
-| **MUST** | M (Must have) | Critical to MVP | Sprint N |
-| **SHOULD** | S (Should have) | High value, deferrable | Sprint N+1 |
-| **COULD** | C (Could have) | Nice-to-have | Backlog |
-| **WONT** | W (Won't have this time) | Out of scope | Future |
-
-**Micro mode:** All FRs have priority MUST (focus only on essential CRUD).
-
-### 5.3 FR Anatomy
-
-Each FR includes:
-- **id:** FR-NNN (sequential)
-- **title:** [Verb] [Object] [Qualifier]
-- **description:** What the system shall do
-- **priority:** MUST/SHOULD/COULD/WONT
-- **actor:** Which actor initiates
-- **linkedRules:** References to BR-XXX identifiers
-- **acceptance:** Testable acceptance criteria
-
----
-
-## 6. Section 4: Permission Matrix & Data Model
-
-### 6.1 RBAC Matrix (Actors × Resources × Operations)
-
-Create a permission matrix for each resource:
-
-```json
-{
-  "permissionMatrix": [
-    {
-      "resource": "Order",
-      "operations": [
-        {
-          "op": "Read",
-          "Admin": true,
-          "Manager": true,
-          "User": true,
-          "Guest": false
-        },
-        {
-          "op": "Create",
-          "Admin": true,
-          "Manager": true,
-          "User": true,
-          "Guest": false
-        },
-        {
-          "op": "Update",
-          "Admin": true,
-          "Manager": true,
-          "User": false,
-          "Guest": false
-        },
-        {
-          "op": "Delete",
-          "Admin": true,
-          "Manager": false,
-          "User": false,
-          "Guest": false
-        }
-      ]
-    }
-  ]
-}
-```
-
-**Micro mode:** 4-role matrix only (Admin, Manager, User, Guest).
-
-### 6.2 Data Model Entities
-
-Define main entities and relationships:
-
-```json
-{
-  "entities": [
-    {
-      "name": "Order",
-      "pluralName": "Orders",
-      "description": "Purchase order entity",
-      "fields": [
-        {
-          "name": "id",
-          "type": "int",
-          "required": true,
-          "key": "primary"
-        },
-        {
-          "name": "orderNumber",
-          "type": "string",
-          "required": true,
-          "unique": true,
-          "length": 20
-        },
-        {
-          "name": "orderDate",
-          "type": "datetime",
-          "required": true
-        },
-        {
-          "name": "status",
-          "type": "enum",
-          "values": ["Draft", "Submitted", "Approved", "Shipped", "Delivered", "Cancelled"],
-          "default": "Draft"
-        }
-      ]
-    }
-  ]
-}
-```
-
-### 6.3 Navigation Hierarchy & UI Structure
-
-**CRITICAL: Define 5 Mandatory SeedData Tables**
-
-The navigation structure implies these mandatory SeedData tables:
-
-```json
-{
-  "navigationHierarchy": [
-    {
-      "level": 1,
-      "menuItem": "Module Name",
-      "icon": "icon-module",
-      "route": "/module",
-      "children": [
-        {
-          "level": 2,
-          "menuItem": "List [Resource]",
-          "route": "/module/list",
-          "seedDataRequired": [
-            "Module_Status (SeedData)",
-            "Module_Priority (SeedData)",
-            "Module_Category (SeedData)",
-            "Module_Type (SeedData)",
-            "Module_Department (SeedData)"
-          ]
-        },
-        {
-          "level": 2,
-          "menuItem": "Create [Resource]",
-          "route": "/module/create"
-        },
-        {
-          "level": 2,
-          "menuItem": "Reports",
-          "route": "/module/reports",
-          "children": [
-            {
-              "level": 3,
-              "menuItem": "Daily Summary",
-              "route": "/module/reports/daily"
-            }
-          ]
-        }
-      ]
-    }
-  ]
-}
-```
-
-**5 Mandatory SeedData Tables:**
-
-1. **Module_Status** - Record statuses (Draft, Approved, Published, Archived)
-2. **Module_Priority** - Priority levels (High, Medium, Low)
-3. **Module_Category** - Classification categories
-4. **Module_Type** - Resource subtypes or classifications
-5. **Module_Department** - Organizational units for filtering/access control
-
-These tables are:
-- Created in migrations before module features
-- Seeded with initial values (5-10 rows each)
-- Used in dropdowns and status filters throughout the UI
-- Referenced in validation and permission checks
-
-**Micro mode:** Minimal: Status and Category only. Skip Priority, Type, Department.
-
-### 6.4 SeedData Core (OBLIGATOIRE)
-
-> **CRITIQUE :** Sans ces SeedData, le module sera invisible dans la navigation et toutes les API retourneront 403.
-
-En plus des 5 tables metier ci-dessus, generer une section `specification.seedDataCore` derivee automatiquement de `specification.navigation` et `specification.permissionMatrix` :
-
-```json
-{
-  "seedDataCore": {
-    "navigationModules": [
-      {
-        "code": "fleet",
-        "label": "Fleet Management",
-        "icon": "Truck",
-        "route": "/business/freebike/fleet",
-        "parentCode": "freebike",
-        "sort": 1
-      }
-    ],
-    "navigationTranslations": [
-      { "moduleCode": "fleet", "language": "fr", "label": "Gestion de Flotte" },
-      { "moduleCode": "fleet", "language": "en", "label": "Fleet Management" }
-    ],
-    "permissions": [
-      { "path": "business.freebike.fleetmanagement.vehicles.read", "action": "read", "description": "Consulter vehicules" }
-    ],
-    "rolePermissions": [
-      { "role": "FreeBike Admin", "permissionPath": "business.freebike.fleetmanagement.*" },
-      { "role": "FreeBike Manager", "permissionPath": "business.freebike.fleetmanagement.vehicles.read" }
-    ],
-    "permissionConstants": [
-      { "constantName": "VehiclesRead", "path": "business.freebike.fleetmanagement.vehicles.read" }
-    ]
-  }
-}
-```
-
-**Regles de derivation :**
-
-1. **navigationModules** : Prendre chaque entree de `specification.navigation.entries[]` avec level = module ou section
-2. **navigationTranslations** : Prendre chaque entree de navigation et generer une traduction par langue definie dans `labels`
-3. **permissions** : Copier EXACTEMENT `specification.permissionMatrix.permissions[]` (chemins complets)
-4. **rolePermissions** : Pour chaque `roleAssignments[]`, expander les wildcards et raccourcis en chemins complets. Chaque `permissionPath` DOIT correspondre a un `permissions[].path` existant
-5. **permissionConstants** : Pour chaque permission, generer un nom PascalCase (ex: `business.freebike.fleetmanagement.vehicles.read` → `VehiclesRead`)
-
-**Verification :** Chaque `rolePermissions[].permissionPath` doit exister dans `permissions[].path`. Si un raccourci est utilise (ex: `vehicles.read` au lieu du chemin complet), c'est une ERREUR.
-
-**Micro mode :** Generer avec les permissions CRUD minimales pour le role Admin uniquement.
-
----
-
-## 7. Section 5: UI Wireframes
-
-### 7.1 Key Screens
-
-For each major UC, sketch wireframe structure:
-
-```markdown
-### Wireframe WF-001: List [Resource]
-
-**Location:** `/module/list`
-
-**Layout:**
-```
-┌─────────────────────────────────────────┐
-│ Module > List [Resource]                │
-├─────────────────────────────────────────┤
-│ [Search] [Filter ▼] [Add New]          │
-├─────────────────────────────────────────┤
-│ ┌─────┬──────────┬────┬──────┐        │
-│ │ ID  │ Name     │... │ Action│        │
-│ ├─────┼──────────┼────┼──────┤        │
-│ │ 001 │ Item 1   │... │ Edit  │        │
-│ │ 002 │ Item 2   │... │ [⋮]   │        │
-│ └─────┴──────────┴────┴──────┘        │
-│                                         │
-│ Page 1 of 10 [◀] [1][2][3]... [▶]     │
-└─────────────────────────────────────────┘
-```
-
-**Components:**
-- Header with breadcrumb
-- Filter bar (by Status, Category, etc.)
-- Sortable data table with [fields]
-- Row actions: Edit, View, Delete (context menu)
-- Pagination controls
-- Empty state: "No [resources] found"
-
-**Responsive:** Full width on desktop, card view on mobile.
-```
-
-### 7.2 Form Validation UI
-
-For Create/Update screens:
-
-```markdown
-### Wireframe WF-002: Create [Resource]
-
-**Location:** `/module/create`
-
-**Form Fields:**
-```
-Field Name (required) *
-┌──────────────────────────┐
-│ [text input]             │ ✓
-└──────────────────────────┘
-Help text: [guidance]
-
-Status (required) *
-┌──────────────────────────┐
-│ [Draft ▼]                │
-└──────────────────────────┘
-
-[Cancel] [Save]
-```
-
-**Validations:**
-- Field Name: required, max 100 chars, no special characters (inline validation)
-- Status: required, dropdown only (no free text)
-- On submit: If invalid, highlight fields and show error messages above form
-- On success: Show success toast and navigate to detail view
-```
-
----
-
-## 8. Section 6: Gherkin Scenarios (BDD)
-
-### 8.1 Feature Definition
-
-Write acceptance criteria in Gherkin format:
-
-```gherkin
-Feature: Order Management - List Orders
-  As a User
-  I want to view a paginated list of orders
-  So that I can find and manage orders efficiently
-
-  Scenario: User views default order list
-    Given I am logged in as a User
-    And I have Read permission on Orders
-    When I navigate to /orders
-    Then I should see the order list
-    And results should be sorted by OrderDate descending
-    And page size should default to 25 items
-    And I should see pagination controls
-
-  Scenario: User filters orders by status
-    Given I am on the order list page
-    And there are orders with different statuses
-    When I select "Approved" from Status filter
-    And I click Apply
-    Then only Approved orders should be displayed
-    And the filter should remain active on the page
-
-  Scenario: User searches for specific order
-    Given I am on the order list page
-    When I enter "ORD-001" in the search box
-    And I press Enter
-    Then only matching orders should be displayed
-    And search term should appear in the search box
-
-  Scenario: Empty state when no orders exist
-    Given I am on the order list page
-    And no orders exist in the system
-    Then I should see "No orders found"
-    And I should see "Create New Order" button
-    And pagination should not be visible
-```
-
-**Gherkin Rules:**
-- **Feature:** Module-level behavior
-- **Scenario:** Individual test case (happy path or alternative)
-- **Given:** Initial state/preconditions
-- **When:** User action
-- **Then:** Expected outcome
-- **And:** Additional steps in same context
-
-**Micro mode:** 2 scenarios max: happy path (List works) + one error case (empty state, validation failure).
-
-### 8.2 Scenario Categories
-
-| Category | Count | Examples |
-|----------|-------|----------|
-| **Happy Path** | 1 per UC | Normal operation succeeds |
-| **Alternative Flows** | 1-2 per UC | Empty state, no permission, etc. |
-| **Validation** | 1 per form | Invalid input rejected with message |
-| **Edge Cases** | 0-1 per UC | Boundary values, special characters |
-| **Error Handling** | 1 per UC | Server error, network failure |
-
----
-
-## 9. Section 7: Validations & Business Messages
-
-### 9.1 Field Validations
-
-For each input field, specify validation rules:
-
-```json
-{
-  "validations": [
-    {
-      "fieldName": "OrderNumber",
-      "rules": [
-        {
-          "type": "required",
-          "message": "Order number is required"
-        },
-        {
-          "type": "unique",
-          "scope": "Order",
-          "message": "This order number already exists"
-        },
-        {
-          "type": "pattern",
-          "pattern": "^ORD-\\d{6}$",
-          "message": "Format must be ORD-XXXXXX (e.g., ORD-001234)"
-        },
-        {
-          "type": "maxLength",
-          "maxLength": 20,
-          "message": "Order number cannot exceed 20 characters"
-        }
-      ]
-    },
-    {
-      "fieldName": "OrderDate",
-      "rules": [
-        {
-          "type": "required",
-          "message": "Order date is required"
-        },
-        {
-          "type": "notFuture",
-          "message": "Order date cannot be in the future"
-        }
-      ]
-    }
-  ]
-}
-```
-
-### 9.2 Business Messages (OBLIGATOIRE - minimum 4 messages)
-
-> **OBLIGATOIRE :** Generer au minimum 4 messages metier dans `specification.messages[]` :
-> - 1 success (ex: RESOURCE_CREATED_SUCCESS)
-> - 1 error CRUD (ex: RESOURCE_CREATION_FAILED)
-> - 1 error validation (ex: RESOURCE_NOT_FOUND)
-> - 1 error permission (ex: PERMISSION_DENIED)
->
-> Pour les modules complexes, ajouter des messages warning (ex: STOCK_LOW_WARNING, SYNC_FAILED_WARNING).
-
-Define user-facing messages for operations:
-
-```json
-{
-  "messages": [
-    {
-      "code": "ORDER_CREATED_SUCCESS",
-      "type": "success",
-      "title": "Order Created",
-      "message": "Order {orderNumber} was created successfully.",
-      "i18nKey": "orders.messages.createdSuccess"
-    },
-    {
-      "code": "ORDER_CREATION_FAILED",
-      "type": "error",
-      "title": "Creation Failed",
-      "message": "Unable to create order. Please check your input and try again.",
-      "i18nKey": "orders.messages.creationFailed"
-    },
-    {
-      "code": "ORDER_NOT_FOUND",
-      "type": "error",
-      "title": "Not Found",
-      "message": "Order {id} does not exist.",
-      "i18nKey": "orders.messages.notFound"
-    },
-    {
-      "code": "PERMISSION_DENIED",
-      "type": "error",
-      "title": "Access Denied",
-      "message": "You do not have permission to {action} this order.",
-      "i18nKey": "common.messages.permissionDenied"
-    }
-  ]
-}
-```
-
----
-
-## 10. Section 8: Data Lifecycle & Cross-Module Patterns
-
-### 10.1 Entity Lifecycle States (OBLIGATOIRE - minimum 1 entite)
-
-> **OBLIGATOIRE :** Pour chaque entite ayant un attribut `Status` ou `State` (enum), definir une state machine dans `specification.lifeCycles[]`.
-> Identifier les entites candidates en parcourant `analysis.entities[].attributes[]` pour trouver celles avec un champ de type enum representant un statut.
-> Minimum : 1 entite avec state machine. Pour un full-module, typiquement 2-4 entites.
-
-Define state transitions for key entities:
-
-```json
-{
-  "lifeCycles": [
-    {
-      "entity": "Order",
-      "states": [
-        {
-          "id": "Draft",
-          "displayName": "Draft",
-          "description": "Order created but not yet submitted",
-          "allowedTransitions": ["Submitted", "Cancelled"],
-          "visibility": "Creator only"
-        },
-        {
-          "id": "Submitted",
-          "displayName": "Submitted for Review",
-          "description": "Order awaiting approval",
-          "allowedTransitions": ["Approved", "Rejected", "Cancelled"],
-          "visibility": "Creator + Manager",
-          "requiresApproval": true
-        },
-        {
-          "id": "Approved",
-          "displayName": "Approved",
-          "description": "Order approved and ready for fulfillment",
-          "allowedTransitions": ["Shipped", "Cancelled"],
-          "visibility": "All",
-          "triggerAction": "CreateFulfillmentTask"
-        },
-        {
-          "id": "Shipped",
-          "displayName": "Shipped",
-          "description": "Order dispatched to customer",
-          "allowedTransitions": ["Delivered", "Cancelled"],
-          "visibility": "All"
-        },
-        {
-          "id": "Delivered",
-          "displayName": "Delivered",
-          "description": "Order received by customer",
-          "allowedTransitions": ["Archived"],
-          "visibility": "All",
-          "isTerminal": true
-        },
-        {
-          "id": "Cancelled",
-          "displayName": "Cancelled",
-          "description": "Order cancelled",
-          "allowedTransitions": [],
-          "visibility": "All",
-          "isTerminal": true
-        }
-      ]
-    }
-  ]
-}
-```
-
-### 10.2 Cross-Module Dependencies
-
-Document how this module interacts with others:
-
-```json
-{
-  "crossModuleDependencies": [
-    {
-      "module": "Orders",
-      "dependsOn": "Customers",
-      "relationship": "Foreign key: Order.CustomerId → Customer.Id",
-      "synchronization": "Order.CustomerName auto-updates when Customer.Name changes",
-      "validation": "CustomerId must exist in Customers table",
-      "cascadeDelete": false
-    },
-    {
-      "module": "Orders",
-      "dependsOn": "Inventory",
-      "relationship": "Order creates InventoryMovement records",
-      "synchronization": "When Order status = Shipped, Inventory.OnHand decreases",
-      "validation": "Order cannot be approved if inventory insufficient",
-      "cascadeDelete": false
-    }
-  ]
-}
-```
-
-### 10.3 Audit & Archival
-
-Document data retention and auditing:
-
-```json
-{
-  "auditingPolicy": {
-    "enabled": true,
-    "trackFields": ["OrderNumber", "Status", "OrderDate", "TotalAmount"],
-    "retentionDays": 2555,
-    "archivalRule": "Orders older than 7 years are archived to cold storage"
-  },
-  "archivalPolicy": {
-    "enabled": true,
-    "archiveAfterDays": 2555,
-    "archiveLocation": "Archive_Orders table",
-    "restoreCapability": true
-  }
-}
-```
-
----
-
-## 11. Execution Workflow
-
-### 11.1 Information Gathering
-
-1. **Load feature.json** via `ba-reader`:
-   - feature.json.scope.* - User goals and constraints
-   - feature.json.analysis.* - Business rules, stakeholder roles
-
-2. **Clarify with user:**
-   - Confirm actor roles and permission levels
-   - Validate use case scope (too many? combine?)
-   - Confirm resource state transitions
-   - Verify SeedData needs
-
-### 11.2 Specification Generation
-
-1. **Define actors** - Map to system roles with base permissions
-2. **Create use cases** - UC-001, UC-002, ... in order of importance
-3. **Define FRs** - FR-001, FR-002, ... linked to BRs
-4. **Build permission matrix** - Actor × Resource × Operation
-5. **Design UI structure** - 5 mandatory SeedData tables, navigation hierarchy
-6. **Sketch wireframes** - Key screens (List, Create, Detail)
-7. **Write Gherkin** - BDD scenarios for each UC
-8. **Define validations** - Field rules and business messages
-9. **Model lifecycle** - State machines, cross-module sync
-10. **Document dependencies** - External modules, cascading operations
-
-### 11.3 Data Model Validation
-
-Ensure:
-- No duplicate entity definitions
-- All FK relationships defined
-- All required fields marked
-- Enum values match business rules
-
----
-
-## 12. Output & Status Update
-
-### 12.1 Write Specification Section
-
-Use `ba-writer.updateSpecification()` to write:
-
-> **INTERDIT :** Ne JAMAIS generer de fichier `specification.json` separe. Toute la specification DOIT rester dans `feature.json.specification`. Un fichier specification.json separe cree une double source de verite et sera ecrase/ignore.
-
-```json
-{
-  "specification": {
-    "actors": [...],
-    "useCases": [...],
-    "functionalRequirements": [...],
-    "permissionMatrix": [...],
-    "entities": [...],
-    "navigationHierarchy": [...],
-    "wireframes": [...],
-    "gherkinScenarios": [...],
-    "validations": [...],
-    "messages": [...],
-    "lifeCycles": [...],
-    "seedDataCore": {...},
-    "crossModuleDependencies": [...],
-    "auditingPolicy": {...},
-    "archivalPolicy": {...}
-  }
-}
-```
-
-### 12.2 Update Status
-
-Use `ba-writer.updateStatus("specified")` to mark specification complete.
-
-### 12.3 User Confirmation
-
-Summarize for user:
-
-```
-✓ Specification complete
-
-Actors defined:     4 (Admin, Manager, User, Guest)
-Use cases created:  8 (UC-001 → UC-008)
-Requirements:       12 FRs linked to business rules
-Permission matrix:  3 resources × 4 actors
-SeedData tables:    5 mandatory (Status, Priority, Category, Type, Department)
-SeedData Core:      5 files (Navigation, Translations, Permissions, RolePermissions, Constants)
-Messages:           6 business messages (success, error, warning)
-UI screens:         6 wireframes (List, Create, Detail, Reports, etc.)
-Gherkin scenarios:  18 scenarios across all UCs
-Validations:        24 field validation rules
-Entity lifecycle:   3 entities with state machines
-
-Next step: Validation (step-03-validate.md)
-```
-
----
-
-## OUTPUT
-
-This step enriches **feature.json** with:
-- **specification** section containing actors, use cases, functional requirements, permission matrix, entities, navigation hierarchy, wireframes, Gherkin scenarios, validations, and data lifecycle
-- **Status:** "specified"
-
-**Delta mode:** Only affected UCs/FRs/permissions modified; existing ones preserved.
-**Micro mode:** Minimal specification with 1-2 UCs, 4-role permissions, basic CRUD FRs, essential SeedData only.