@atlashub/smartstack-cli 3.9.0 → 3.12.0

package/templates/skills/business-analyse/steps/step-03a-data.md

@@ -1,432 +1,42 @@
 ---
 name: step-03a-data
-description: Per-module specification - sections, entities, business rules, questionnaires (data & logic phase)
+description: Per-module data specification - REDIRECTS to step-03a1 (refactored into 2 sub-steps)
 model: opus
-next_step: steps/step-03b-ui.md
+next_step: steps/step-03a1-setup.md
 ---
 
-> **Context files:** `_shared.md` | `_elicitation.md` | `_architecture.md` | `_module-loop.md`
+> **NOTICE:** This step has been refactored into 2 sub-steps for better context management.
 
-# Step 3a: Specification - Data & Logic
+# Step 3a: Specification - Data & Logic (Entry Point)
 
-## MANDATORY EXECUTION RULES
+This step has been divided into 2 focused sub-steps:
 
-- ALWAYS use ULTRATHINK mode
-- This step is EXECUTED ONCE PER MODULE in topological dependency order
-- ALWAYS check workflow state to determine current module
-- ALWAYS reference completed modules when specifying current one
-- **MANDATORY:** Generate and validate an ASCII/SVG mockup for EVERY section (not optional)
-- ALL questions via AskUserQuestion tool
-- ALL communication in `{language}`
-- NEVER skip per-module validation
-- **ID NAMING RULE (MANDATORY, NO EXCEPTION):**
-  All IDs MUST include a module prefix to guarantee application-wide uniqueness.
-  The prefix is derived from the module code initials (2-4 chars):
-    UserManagement → UM | VehicleManagement → VM | PartsInventory → PI
-    RepairManagement → RM | MaintenanceSchedule → MS | DataSync → DS
-    Notifications → NT | Dashboard → DB | Orders → OR | Customers → CU
-
-  Patterns:
-    UC-{PREFIX}-{NNN}        → UC-RM-001, UC-PI-003
-    BR-{CAT}-{PREFIX}-{NNN}  → BR-VAL-RM-001, BR-CALC-PI-002
-    FR-{PREFIX}-{NNN}        → FR-RM-001
-    OBJ-{PREFIX}-{NNN}       → OBJ-RM-001
-    AC-{PREFIX}-{NNN}        → AC-RM-001
-    RISK-{PREFIX}-{NNN}      → RISK-RM-001
-
-  NEVER use bare IDs (UC-001, BR-VAL-001) in multi-module mode.
-- **SCHEMA CONFORMITY RULE:**
-  ALL data MUST fit within the defined feature-schema.json structure.
-  NEVER create custom top-level fields (KPIDefinitions, ChartConfigurations, etc.)
-  Dashboard modules MUST use specification.dashboards[] (it exists in the schema).
-  If truly needed, use specification.extensions: {} (additionalProperties: true).
-
-## YOUR TASK
-
-Specify one module's data model and business logic: walk through sections, define entities, business rules, and validate with client before proceeding to UI specification.
+1. **step-03a1-setup.md** - Module setup, sections walkthrough, questionnaires, cross-refs
+2. **step-03a2-analysis.md** - Analysis section: objectives, entities, business rules, process flow
 
 ---
 
-## EXECUTION SEQUENCE
-
-### 1. Determine Current Module
-
-```
-ba-reader.readApplicationContext({feature_id})
-→ Read metadata.workflow: moduleOrder, currentModuleIndex, completedModules
-→ currentModule = moduleOrder[currentModuleIndex]
-→ Display: "═══ Module {currentModuleIndex + 1}/{moduleOrder.length}: {currentModule} ═══"
-```
-
-IF module already specified (status = "specified" in master):
-  Increment currentModuleIndex, re-check
-  IF all modules specified → Load step-04-consolidation.md, STOP
-
-### 2. Initialize Module Feature.json
-
-```
-// Create or load module-level feature.json
-ba-writer.create({
-  scope: "module",
-  applicationRef: {feature_id},
-  moduleCode: {currentModule.code},
-  path: "docs/business/{app}/{module_code}/business-analyse/v1.0/feature.json"
-})
-
-// Inherit application roles from master
-ba-reader.readApplicationContext({feature_id})
-→ Copy cadrage.applicationRoles → module.applicationContext.applicationRoles
-```
-
-// Update module status in master: "pending" → "in-progress"
-ba-writer.updateModuleStatus({feature_id}, {currentModule.code}, "in-progress")
-
-### 2-ter. Derive Module Discovery Section (MANDATORY)
-
-> **The module feature.json MUST have a `discovery` section.** In multi-module mode, derive it from the parent application's `cadrage`. In single-module mode, it should already exist from step-01.
-
-```
-ba-reader.readApplicationContext({feature_id})
-→ Read cadrage: problem, asIs, toBe, trigger, stakeholders, risks, acceptanceCriteria
-
-// Filter to this module's scope
-moduleScope = cadrage.coverageMatrix.filter(cm => cm.module === currentModule.code)
-moduleStakeholders = cadrage.stakeholders.filter(s => s.tasks relevant to this module)
-moduleRisks = cadrage.risks.filter(r => r related to this module)
-
-ba-writer.enrichSection({
-  featureId: {module_feature_id},
-  section: "discovery",
-  data: {
-    problem: cadrage.problem,
-    asIs: cadrage.asIs,
-    toBe: cadrage.toBe,
-    trigger: cadrage.trigger,
-    stakeholders: moduleStakeholders,
-    scope: {
-      mustHave: moduleScope.filter(s => s.category === "mustHave").map(s => s.item),
-      shouldHave: moduleScope.filter(s => s.category === "shouldHave").map(s => s.item),
-      couldHave: moduleScope.filter(s => s.category === "couldHave").map(s => s.item),
-      outOfScope: []
-    },
-    risks: moduleRisks,
-    acceptanceCriteria: cadrage.acceptanceCriteria.filter(ac => relevant to module),
-    codebaseContext: cadrage.codebaseContext
-  }
-})
-```
-
-> **STRUCTURE CARD: discovery** — Same format as cadrage but module-scoped.
-> Fields: `problem`, `asIs`, `toBe`, `trigger`, `stakeholders[]`, `scope{}`, `risks[]`, `acceptanceCriteria[]`, `codebaseContext`, `openQuestions[]`
-
-### 2-bis. Coverage Verification (MANDATORY)
-
-> **Before specifying any module, verify that the coverageMatrix from cadrage covers this module.**
-
-```
-ba-reader.readApplicationContext({feature_id})
-→ Read cadrage.coverageMatrix[]
-→ Filter entries where module = {currentModule.code}
-→ Group by category: mustHave, shouldHave, couldHave
-```
-
-Display to client:
-```
-Module {currentModule}: Coverage from original brief
-
-| # | Requirement | Category |
-|---|-------------|----------|
-| 1 | {item} | {category} |
-| ... | ... | ... |
-
-Total: {N} requirements mapped to this module
-  - Must-have: {count}
-  - Should-have: {count}
-  - Could-have: {count}
-```
-
-**VALIDATION:** If mustHave count = 0 AND module is in must priority:
-  → WARNING: "Module {currentModule} is must-priority but has no must-have requirements in coverageMatrix. Verify cadrage coverage."
-
-**POST-SPECIFICATION CHECK (at end of module, before advancing):**
-  For EACH mustHave item in coverageMatrix for this module:
-    → Verify at least 1 UC exists that covers this requirement
-    → If uncovered: BLOCK and ask client to either add a UC or reclassify the requirement
-
-### 3. Section Walkthrough with Client
-
-> **This is the key interactive phase aligned with the 5-level SmartStack hierarchy.**
-> Level 3 = Module, Level 4 = Section, Level 5 = Resource
-
-#### 3a. Identify Module Sections
-
-For each module, propose standard sections based on module type:
-
-| Module Type | Typical Sections |
-|-------------|-----------------|
-| data-centric | list, detail, create, edit |
-| workflow | list, detail, create, edit, approve, history |
-| integration | list, detail, config, sync, logs |
-| reporting | dashboard, detail, export, schedule |
-| full-module | list, detail, create, edit, approve, history, reports, settings |
-
-Ask via AskUserQuestion:
-
-```
-question: "Quelles sections le module {currentModule} doit-il avoir ?"
-header: "Sections"
-multiSelect: true
-options:
-  - label: "Liste"
-    description: "Page de liste avec filtres, tri et pagination"
-  - label: "Détail"
-    description: "Page de détail d'un enregistrement"
-  - label: "Création/Édition"
-    description: "Formulaire de création et de modification"
-  - label: "Validation/Approbation"
-    description: "Workflow de validation avec changement de statut"
-  - label: "Dashboard"
-    description: "Tableau de bord avec KPIs, graphiques (Recharts) et métriques clés"
-```
-
-#### 3a-depth. Determine Specification Depth
-
-> **Based on module complexity and type, determine how deeply to specify sections and resources.**
-> **This avoids over-specifying simple modules and under-specifying complex ones.**
-
-Read from application master:
-```
-ba-reader.readApplicationContext({feature_id})
-→ module = modules.find(m => m.code === currentModule)
-→ complexity = module.estimatedComplexity   // simple | medium | complex
-→ featureType = module.featureType          // data-centric | workflow | integration | reporting | full-module
-```
-
-**Depth decision matrix:**
-
-| Complexity | featureType | Depth | Behavior |
-|---|---|---|---|
-| simple | data-centric | **convention** | Auto-generate sections + resources from entities. Quick client validation. |
-| simple | reporting | **convention** | Standard dashboard template. Quick validation. |
-| simple | * | **convention** | Standard sections for featureType. Quick validation. |
-| medium | data-centric | **override** | Auto-generate then ask client which sections to customize. |
-| medium | workflow | **full** | State machine required → always full. |
-| medium | * | **override** | Auto-generate then ask client to customize. |
-| complex | * | **full** | Full specification: state machine, typed columns, conditional actions. |
-| * | workflow | **full** | Always full for workflow modules (state machine is mandatory). |
-
-Display to client:
-```
-"Module {currentModule}: complexité {complexity}, type {featureType} → profondeur: {depth}"
-```
+## Automatic Redirect
 
-**IF depth = convention:**
-  - Execute 3a-infer (auto-inference) → generates sections + resources
-  - Execute 3b (wireframes) for each section
-  - Skip 3a-bis detailed walkthrough → present auto-generated spec for quick validation
-  - Ask client: "La spécification auto-générée convient-elle, ou souhaitez-vous personnaliser certaines sections ?"
-    - If client says OK → proceed to step 4 (questionnaires)
-    - If client wants changes → switch to **override** for specified sections
+**Loading:** `./step-03a1-setup.md`
 
-**IF depth = override:**
-  - Execute 3a-infer (auto-inference) → generates base sections + resources
-  - Ask client: "Quelles sections souhaitez-vous personnaliser ?"
-  - For selected sections → execute full 3a-bis + 3b + 3b-ter
-  - For other sections → keep auto-generated spec
-
-**IF depth = full:**
-  - Execute standard flow: 3a-bis → 3b → 3b-bis → 3b-ter → 3c → 3d (as currently defined below)
-  - PLUS: 3a-state (state machine definition) for entities with status fields
-
-#### 3a-infer. Auto-Infer Resources from Entities (Convention/Override)
-
-> **For convention and override depths, auto-generate resource details from entity definitions.**
-> **The goal: produce a complete spec without manual input, that the client only validates.**
-
-**Prerequisites:** Entity attributes must be defined (from step 6) OR anticipated from decomposition.
-
-See [references/spec-auto-inference.md](../references/spec-auto-inference.md) for complete inference rules:
-- Entity attribute → SmartTable column mapping (9 type rules)
-- Entity attribute → SmartForm field mapping (8 type rules)
-- Auto-generated sections per featureType (5 types)
-- Section generation rules (list, create, detail, edit, dashboard)
-- Status/lifecycle enhancement rules
-
-Write auto-generated sections to `specification.sections[]` via ba-writer.enrichSection()
-
-### 4. Conditional Questionnaires
-
-Based on module type, load questionnaires per-module:
-
-| Condition | Category | Questionnaire |
-|-----------|----------|---------------|
-| Always | 04 | `questionnaire/04-data.md` |
-| Has UI sections | 07 | `questionnaire/07-ui.md` |
-| Has lifecycle | 11 | `questionnaire/11-data-lifecycle.md` |
-| Has migration needs | 12 | `questionnaire/12-migration.md` |
-| References other modules | 13 | `questionnaire/13-cross-module.md` |
-| Documentation needed | 10 | `questionnaire/10-documentation.md` |
-
-Ask via AskUserQuestion, 1-2 batches per category.
-
-#### Store Documentation Requirements
-
-If questionnaire 10 was loaded, persist answers in feature.json:
-
-```
-ba-writer.enrichSection({
-  featureId: {feature_id},
-  section: "documentation",
-  data: {
-    userDocRequired: {Q10.1 answer == "Yes"},
-    techDocRequired: {Q10.2 answer == "Yes"},
-    status: "pending"
-  }
-})
-```
-
-This data will be consumed by `/application` step-08 to auto-generate in-app documentation.
-
-### 5. Cross-Module References
-
-> Reference completed modules to help define current one.
-
-```
-completedModules = ba-reader.getCompletedModulesSummary({feature_id})
-→ Returns max 100 lines summary: entity names, key BRs, permissions
-
-Display: "Modules déjà spécifiés : {completedModules.map(m => m.code).join(', ')}"
-```
-
-For each completed module's entities, ask:
-
-```
-question: "Le module {currentModule} référence-t-il des entités de {completedModule} ?"
-header: "Références"
-multiSelect: true
-options:
-  - label: "{Entity1} (FK)"
-    description: "Référence directe via clé étrangère"
-  - label: "{Entity2} (Lookup)"
-    description: "Table de référence / lookup"
-  - label: "Aucune"
-    description: "Pas de référence à {completedModule}"
-```
-
-### 6. Analysis Section
-
-#### 6a. Objectives
-
-Define measurable business objectives for this module:
-
-> **STRUCTURE CARD: analysis.objectives[]**
-> ```json
-> { "id": "OBJ-{PREFIX}-001", "objective": "Reduce order processing time", "metric": "Average time to fulfillment", "target": "< 4 hours" }
-> ```
-
-#### 6b. Entity Definition
-
-Define entities for this module (business attributes, not technical):
-
-> **STRUCTURE CARD: analysis.entities[]** — Field names are EXACT. Do NOT deviate.
-> ```json
-> {
->   "name": "PascalCase",
->   "description": "1-2 sentences describing the entity purpose",
->   "attributes": [
->     {
->       "name": "attributeName",
->       "description": "What this attribute represents",
->       "required": true,
->       "unique": false,
->       "validation": "Format: XXX-NNNNN, max 100 chars, etc."
->     }
->   ],
->   "relationships": [
->     { "target": "OtherEntity", "type": "1:1|1:N|N:1|N:M", "description": "description" }
->   ]
-> }
-> ```
-> **FORBIDDEN fields in attributes:** Do NOT use `type`, `values`, `rules`.
-> Use `description` to explain what the attribute is, `validation` for format/constraint rules, `unique` as boolean.
-
-#### 6c. Process Flow
-
-Define the main business process flow for this module (not lifecycle — that's in 8j):
-
-> **STRUCTURE CARD: analysis.processFlow**
-> ```json
-> {
->   "entryPoints": ["User navigates to module", "System event triggers action"],
->   "mainFlow": [
->     { "step": 1, "actor": "Manager", "action": "Opens the list", "system": "Displays filtered records" },
->     { "step": 2, "actor": "Manager", "action": "Creates a record", "system": "Validates BR-VAL-{PREFIX}-001" },
->     { "step": 3, "actor": "System", "action": "Saves record", "system": "Sends notification" }
->   ],
->   "decisionPoints": [
->     { "condition": "Is amount > threshold?", "ifTrue": "Route to approver", "ifFalse": "Auto-approve", "rule": "BR-WF-{PREFIX}-001" }
->   ],
->   "alternativeFlows": ["Bulk import via CSV", "Automatic sync from SFTP"]
-> }
-> ```
-> **FORBIDDEN:** Do NOT put lifecycle/state machine data here. Use `specification.lifeCycles[]` for that.
-
-#### 6d. Data Lifecycle
-
-Define data retention and lifecycle policies:
-
-> **STRUCTURE CARD: analysis.dataLifecycle**
-> ```json
-> {
->   "retentionPeriod": "7 years",
->   "archiveStrategy": "Move to cold storage after 2 years",
->   "gdprCompliance": "PII anonymized on request, data export available",
->   "states": [
->     { "name": "active", "transitions": ["archived", "deleted"] },
->     { "name": "archived", "transitions": ["active"] },
->     { "name": "deleted", "transitions": [] }
->   ]
-> }
-> ```
-
-### 7. Business Rules Extraction
-
-Extract business rules specific to this module:
-
-> **STRUCTURE CARD: analysis.businessRules[]** — Field names are EXACT. Do NOT deviate.
-> ```json
-> {
->   "id": "BR-VAL-{PREFIX}-001",
->   "name": "Short rule name",
->   "category": "validation|calculation|workflow|security|data",
->   "statement": "IF {condition} THEN {consequence} ELSE {alternative}",
->   "priority": "must|should|could",
->   "conditions": ["Condition 1", "Condition 2"],
->   "examples": [{ "input": "Order total $5000, budget $2000", "expected": "Order rejected" }],
->   "testability": "Via unit test with mock data / integration test"
-> }
-> ```
-> **MANDATORY fields:** `id`, `name`, `category`, `statement`, `priority`
-> **FORBIDDEN fields:** Do NOT use `rule`, `condition` (singular), `action`. Use `name` + `statement` (IF/THEN/ELSE format) + `conditions` (array).
-> **ID PATTERN:** `BR-{CAT}-{PREFIX}-{NNN}` where CAT = VAL|CALC|WF|SEC|DATA, PREFIX = module initials (2-4 chars)
-> **category values:** lowercase only: `validation`, `calculation`, `workflow`, `security`, `data`
+The data specification process will execute in sequence:
+- step-03a1-setup → step-03a2-analysis → step-03b-ui
 
 ---
 
-## SELF-VERIFICATION (MANDATORY before loading step-03b-ui)
+## Why Refactored?
 
-Before proceeding to step-03b-ui.md, VERIFY:
+**Before:** 468 lines in single file (exceeded 400-line recommendation)
 
-1. **Module feature.json exists** at expected path (`docs/business/{app}/{module}/business-analyse/v{X.Y}/feature.json`)
-2. **Module feature.json has analysis section** with `entities[]` (at least 1) and `businessRules[]` (at least 1)
-3. **Module status in master** = "in-progress" (set by section 2 above)
-4. **Master modules[].featureJsonPath** for this module ≠ null (set by ba-writer.create)
-5. **Sections identified** with clear roles and entities assigned
+**After:** 2 focused files (~320 + ~150 lines)
 
-**IF any check fails → FIX before proceeding.** Do NOT load step-03b-ui with incomplete data.
+**Benefits:**
+- Better context management
+- Clearer separation: setup vs analysis
+- Module preparation separated from entity/logic definition
+- Reduced cognitive load per step
 
 ---
 
-## NEXT STEP
-
-Load: `steps/step-03b-ui.md`
+**Proceeding to step-03a1-setup.md...**