@atlashub/smartstack-cli 3.4.0 → 3.4.1

package/templates/skills/business-analyse/steps/step-06-extract.md

@@ -1,648 +0,0 @@
----
-name: step-06-extract
-description: Extract interactive HTML document data into feature.json - zero information loss
-model: sonnet
-next_step: null
----
-
-> **Context files:** `_shared.md`
-
-# Step 6: Extraction depuis le document interactif
-
-## REGLES D'EXECUTION
-
-- TOUJOURS lire le fichier JSON exporte avant toute operation
-- TOUJOURS mapper CHAQUE element sans exception (zero perte d'information)
-- TOUJOURS utiliser ba-writer pour ecrire dans feature.json
-- TOUJOURS afficher un resume comparatif avant/apres extraction
-- TOUJOURS demander confirmation avant d'ecraser un feature.json existant
-- COMMUNICATION en `{language}` (depuis metadata ou config)
-
-## VOTRE TACHE
-
-Lire le fichier JSON exporte depuis le document HTML interactif et transformer toutes les donnees client en feature.json conforme au schema. Chaque element saisi par le client doit se retrouver dans le feature.json sans perte ni alteration.
-
----
-
-## SEQUENCE D'EXECUTION
-
-### 1. Lire le fichier JSON exporte
-
-```
-Lire le fichier passe en argument : {extract_path}
-→ Parser le JSON
-→ Valider la structure minimale : metadata, cadrage, modules
-```
-
-**Structure attendue du JSON exporte :**
-```json
-{
-  "metadata": {
-    "applicationName": "...",
-    "applicationId": "...",
-    "version": "...",
-    "createdAt": "...",
-    "lastModified": "...",
-    "exportedAt": "..."
-  },
-  "cadrage": {
-    "problem": { "description": "", "impactedPeople": "", "history": "", "trigger": "", "consequences": "" },
-    "current": { "tools": "", "painPoints": "", "errors": "", "steps": [] },
-    "vision": { "changes": "", "results": "", "successSign": "" },
-    "stakeholders": [{ "role": "", "function": "", "tasks": [], "frequency": "", "access": "", "frustrations": "" }],
-    "scope": {
-      "vital": [{ "name": "", "description": "" }],
-      "important": [],
-      "optional": [],
-      "excluded": []
-    },
-    "risks": [{ "description": "", "probability": "", "impact": "", "mitigation": "" }],
-    "assumptions": "",
-    "success": { "definition": "", "metrics": "", "timeline": "", "minimumConditions": "" }
-  },
-  "modules": [{ "code": "", "name": "", "description": "", "featureType": "", "priority": "", "entities": [], "status": "" }],
-  "dependencies": [{ "from": "", "to": "", "description": "" }],
-  "moduleSpecifications": {
-    "{code}": {
-      "module": {},
-      "useCases": [{ "id": "", "name": "", "actor": "", "steps": "", "alternative": "" }],
-      "businessRules": [{ "id": "", "name": "", "category": "", "statement": "", "example": "" }],
-      "entities": [{ "name": "", "description": "", "attributes": [{ "name": "", "description": "" }], "relationships": [] }],
-      "permissions": [],
-      "notes": ""
-    }
-  },
-  "consolidation": {
-    "interactions": [],
-    "e2eFlows": [{ "name": "", "steps": [{ "module": "", "action": "" }], "actors": "", "diagram": "" }]
-  },
-  "artifacts": {
-    "wireframes": {
-      "{moduleCode}": [
-        { "screen": "", "section": "", "format": "ascii|svg", "content": "", "description": "",
-          "elements": [], "actions": [], "componentMapping": [], "layout": {}, "permissionsRequired": [] }
-      ]
-    },
-    "e2eFlows": [
-      { "name": "", "diagram": "", "steps": [], "actors": "", "modules": "" }
-    ],
-    "dependencyGraph": {
-      "nodes": [{ "id": "", "label": "", "type": "" }],
-      "edges": [{ "from": "", "to": "", "description": "" }]
-    }
-  }
-}
-```
-
-SI le fichier est invalide ou manquant → STOP avec message d'erreur.
-
-### 2. Determiner l'application et le contexte
-
-```
-application_name = metadata.applicationName OU metadata.applicationId
-version = metadata.version OU "1.0"
-language = "fr" (par defaut, le document HTML est en francais)
-```
-
-Verifier si un feature.json existe deja :
-```
-ba-reader.findFeature(application_name)
-```
-
-SI feature.json existe :
-  → Demander via AskUserQuestion :
-  ```
-  question: "Un feature.json existe deja pour cette application. Que souhaitez-vous faire ?"
-  header: "Conflit"
-  options:
-    - label: "Remplacer"
-      description: "Ecraser le feature.json existant avec les donnees du document interactif"
-    - label: "Fusionner"
-      description: "Fusionner les nouvelles donnees avec l'existant (priorite au document interactif)"
-    - label: "Nouvelle version"
-      description: "Creer une nouvelle version (v1.1) en conservant l'ancien"
-  ```
-
-### 3. Mapper le cadrage
-
-**Transformation : HTML export → feature.json cadrage**
-
-| Source (export JSON) | Destination (feature.json) |
-|---------------------|---------------------------|
-| `cadrage.problem.description` | `cadrage.problem` |
-| `cadrage.problem.impactedPeople` | `cadrage.problem` (append) |
-| `cadrage.problem.history` | `cadrage.problem` (append) |
-| `cadrage.problem.trigger` | `cadrage.trigger` |
-| `cadrage.problem.consequences` | `cadrage.problem` (append) |
-| `cadrage.current.tools` | `cadrage.asIs` |
-| `cadrage.current.steps[]` | `cadrage.asIs` (append process steps) |
-| `cadrage.current.painPoints` | `cadrage.asIs` (append) |
-| `cadrage.current.errors` | `cadrage.asIs` (append) |
-| `cadrage.vision.changes` | `cadrage.toBe` |
-| `cadrage.vision.results` | `cadrage.toBe` (append) |
-| `cadrage.vision.successSign` | `cadrage.toBe` (append) |
-| `cadrage.stakeholders[]` | `cadrage.stakeholders[]` (voir mapping detaille) |
-| `cadrage.scope.vital[]` | `cadrage.globalScope.mustHave[]` |
-| `cadrage.scope.important[]` | `cadrage.globalScope.shouldHave[]` |
-| `cadrage.scope.optional[]` | `cadrage.globalScope.couldHave[]` |
-| `cadrage.scope.excluded[]` | `cadrage.globalScope.outOfScope[]` |
-| `cadrage.risks[]` | `cadrage.risks[]` (voir mapping detaille) |
-| `cadrage.assumptions` | `cadrage.risks[]` (type: "assumption") |
-| `cadrage.success.definition` | `cadrage.acceptanceCriteria[]` |
-| `cadrage.success.metrics` | `cadrage.acceptanceCriteria[]` |
-| `cadrage.success.timeline` | `cadrage.acceptanceCriteria[]` |
-| `cadrage.success.minimumConditions` | `cadrage.acceptanceCriteria[]` |
-
-**Mapping detaille des parties prenantes :**
-
-Pour chaque `cadrage.stakeholders[i]` :
-```json
-{
-  "role": stakeholders[i].role,
-  "function": stakeholders[i].function,
-  "involvement": mapAccessToInvolvement(stakeholders[i].access),
-  "tasks": stakeholders[i].tasks,
-  "frequency": stakeholders[i].frequency,
-  "painPoints": [stakeholders[i].frustrations]
-}
-```
-
-Mapping `access` → `involvement` :
-| access (HTML) | involvement (feature.json) |
-|--------------|---------------------------|
-| admin | decision-maker |
-| manager | approver |
-| contributor | end-user |
-| viewer | informed |
-
-**Mapping detaille des risques :**
-
-Pour chaque `cadrage.risks[i]` :
-```json
-{
-  "id": "RISK-" + String(i + 1).padStart(3, '0'),
-  "type": "business",
-  "description": risks[i].description,
-  "probability": risks[i].probability,
-  "impact": risks[i].impact,
-  "priority": computePriority(risks[i].probability, risks[i].impact),
-  "mitigation": risks[i].mitigation
-}
-```
-
-Pour les hypotheses (texte libre `cadrage.assumptions`) :
-```
-Decouper le texte par lignes
-Pour chaque ligne non vide, creer un risque :
-{
-  "id": "RISK-ASM-" + index,
-  "type": "assumption",
-  "description": ligne,
-  "probability": "medium",
-  "impact": "medium",
-  "priority": "medium",
-  "mitigation": "A verifier avant le demarrage du projet"
-}
-```
-
-**Mapping de la couverture :**
-
-Construire `cadrage.coverageMatrix[]` a partir du scope :
-```
-Pour chaque item dans scope.vital :
-  { "item": item.name, "category": "mustHave", "module": assignModule(item), "notes": item.description }
-Pour chaque item dans scope.important :
-  { "item": item.name, "category": "shouldHave", "module": assignModule(item), "notes": item.description }
-Pour chaque item dans scope.optional :
-  { "item": item.name, "category": "couldHave", "module": assignModule(item), "notes": item.description }
-Pour chaque item dans scope.excluded :
-  { "item": item.name, "category": "outOfScope", "module": null, "notes": item.description }
-```
-
-`assignModule(item)` : Si un seul module, assigner ce module. Si plusieurs modules, chercher le module dont le nom ou les entites correspondent le mieux a l'item.
-
-**Mapping des roles applicatifs :**
-
-Deriver `cadrage.applicationRoles[]` a partir des profils stakeholders :
-```
-Pour chaque stakeholder unique par niveau d'acces :
-{
-  "role": "{App} " + formatRole(access),
-  "description": stakeholder.function,
-  "level": access,
-  "permissionPattern": "business.{app}." + (access === "admin" ? "*" : "...")
-}
-```
-
-**Ecriture :**
-```
-ba-writer.enrichSection({
-  featureId: {feature_id},
-  section: "cadrage",
-  data: { problem, asIs, toBe, trigger, stakeholders, globalScope, applicationRoles, risks, acceptanceCriteria, coverageMatrix, codebaseContext }
-})
-ba-writer.updateStatus({feature_id}, "framed")
-```
-
-### 4. Mapper les modules
-
-Pour chaque `modules[i]` du JSON exporte :
-```json
-{
-  "code": modules[i].code,
-  "description": modules[i].description,
-  "featureType": modules[i].featureType,
-  "dependencies": deriveDependencies(modules[i].code),
-  "dependents": deriveDependents(modules[i].code),
-  "status": "pending",
-  "featureJsonPath": null,
-  "priority": modules[i].priority,
-  "sortOrder": computeSortOrder(modules[i].code),
-  "entities": modules[i].entities,
-  "estimatedComplexity": estimateComplexity(modules[i].code)
-}
-```
-
-`deriveDependencies(code)` : filtrer `dependencies[]` ou `from === code`, retourner les `to`
-`deriveDependents(code)` : filtrer `dependencies[]` ou `to === code`, retourner les `from`
-`computeSortOrder(code)` : depuis le tri topologique
-`estimateComplexity(code)` : basee sur le nombre d'entites et de cas d'utilisation du module
-
-**Construire le graphe de dependances :**
-```json
-{
-  "edges": dependencies.map(d => ({ "from": d.from, "to": d.to, "type": "FK", "description": d.description })),
-  "topologicalOrder": computeTopologicalOrder(),
-  "layers": computeLayers()
-}
-```
-
-**Ecriture :**
-```
-ba-writer.enrichModuleRegistry({
-  featureId: {feature_id},
-  modules: [mapped modules],
-  dependencyGraph: { edges, topologicalOrder, layers }
-})
-ba-writer.updateStatus({feature_id}, "decomposed")
-```
-
-### 5. Mapper les specifications par module
-
-Pour chaque module dans l'ordre topologique :
-
-#### 5a. Creer le feature.json du module
-
-```
-ba-writer.create({
-  scope: "module",
-  applicationRef: {feature_id},
-  moduleCode: {module.code},
-  path: "docs/business/{app}/{module_code}/business-analyse/v1.0/feature.json"
-})
-```
-
-#### 5b. Mapper la section discovery
-
-Deriver de la cadrage, filtree pour ce module (meme logique que step-03 section 2-ter).
-
-#### 5c. Mapper les cas d'utilisation
-
-Pour chaque `moduleSpecifications[code].useCases[i]` :
-```json
-{
-  "id": "UC-{PREFIX}-" + String(i + 1).padStart(3, '0'),
-  "name": uc.name,
-  "primaryActor": uc.actor,
-  "permission": "business.{app}.{module}.{inferAction(uc.name)}",
-  "preconditions": [],
-  "postconditions": [],
-  "mainScenario": parseSteps(uc.steps),
-  "alternativeScenarios": uc.alternative ? [{ "name": "Cas alternatif", "steps": [uc.alternative] }] : [],
-  "errorScenarios": [],
-  "linkedRules": linkToBusinessRules(uc, moduleSpec.businessRules)
-}
-```
-
-`parseSteps(text)` : Decouper par lignes, retourner en tableau.
-`inferAction(name)` : Extraire le verbe (Creer→create, Modifier→update, Supprimer→delete, Consulter→read, Valider→approve, Exporter→export).
-`linkToBusinessRules(uc, rules)` : Chercher les regles dont le statement mentionne des concepts similaires au nom du UC.
-
-#### 5d. Mapper les regles metier
-
-Pour chaque `moduleSpecifications[code].businessRules[i]` :
-```json
-{
-  "id": "BR-{CAT}-{PREFIX}-" + String(i + 1).padStart(3, '0'),
-  "name": br.name,
-  "category": br.category,
-  "statement": br.statement,
-  "priority": "must",
-  "conditions": extractConditions(br.statement),
-  "examples": br.example ? [{ "input": br.example, "expected": "Selon la regle" }] : [],
-  "testability": "Via test unitaire"
-}
-```
-
-`{CAT}` derive de `category` : validation→VAL, calculation→CALC, workflow→WF, security→SEC, data→DATA
-`extractConditions(statement)` : Extraire les conditions depuis le texte "Si..." en tableau.
-
-#### 5e. Mapper les entites
-
-Pour chaque `moduleSpecifications[code].entities[i]` :
-```json
-{
-  "name": toPascalCase(ent.name),
-  "description": ent.description,
-  "attributes": ent.attributes.map(a => ({
-    "name": toCamelCase(a.name),
-    "description": a.description,
-    "required": true,
-    "unique": false,
-    "validation": ""
-  })),
-  "relationships": parseRelationships(ent.relationships)
-}
-```
-
-`parseRelationships(rels)` : Pour chaque relation texte "Nom - Description", extraire :
-```json
-{ "target": toPascalCase(nom), "type": "1:N", "description": description }
-```
-
-#### 5f. Mapper les permissions
-
-Transformer le format `permissions: ["Role|Action"]` en matrice structuree :
-```json
-{
-  "permissions": derivePermissionPaths(code, actions),
-  "roleAssignments": deriveRoleAssignments(code, permissions)
-}
-```
-
-#### 5g. Generer les sections, wireframes et seedDataCore
-
-Inferer automatiquement a partir des entites et du type de module (meme logique que step-03 section 3a-infer).
-
-#### 5h. Ecrire le feature.json du module
-
-```
-ba-writer.enrichSection({ featureId: moduleFeatureId, section: "analysis", data: { objectives, entities, businessRules, processFlow, dataLifecycle } })
-ba-writer.enrichSection({ featureId: moduleFeatureId, section: "specification", data: { actors, useCases, functionalRequirements, permissionMatrix, navigation, seedDataCore, sections, uiWireframes } })
-ba-writer.updateModuleStatus({feature_id}, {module.code}, "specified")
-```
-
-### 6. Mapper la consolidation
-
-Si plusieurs modules :
-```
-ba-writer.enrichSection({
-  featureId: {feature_id},
-  section: "consolidation",
-  data: {
-    crossModuleInteractions: dependencies.map(d => ({
-      "fromModule": d.from, "toModule": d.to,
-      "interactionType": "FK-reference",
-      "description": d.description,
-      "entities": []
-    })),
-    e2eFlows: consolidation.e2eFlows.map(flow => ({
-      "name": flow.name,
-      "modules": [...new Set(flow.steps.map(s => s.module))],
-      "steps": flow.steps.map(s => ({
-        "module": s.module,
-        "action": s.action,
-        "permission": "",
-        "dataFlow": ""
-      }))
-    })),
-    permissionCoherence: { rolesConsistent: true, pathFormatConsistent: true, hierarchyRespected: true, conflicts: [], warnings: [] },
-    decision: { approved: true, reason: "Extracted from interactive document", approvedBy: "Client", approvedAt: new Date().toISOString() }
-  }
-})
-ba-writer.updateStatus({feature_id}, "consolidated")
-```
-
-### 6-bis. Extraire et reconstituer les artefacts visuels (NEW)
-
-> Visual artifacts (wireframes, E2E diagrams, dependency graph) are extracted from the exported JSON and reconstituted into feature.json.
-
-**IF** `artifacts` exists in exported JSON:
-
-#### Extract wireframes per module
-
-Pour chaque module dans `artifacts.wireframes`:
-
-```
-FOR EACH moduleCode IN artifacts.wireframes:
-  moduleWireframes = artifacts.wireframes[moduleCode]
-
-  // Locate the module feature.json
-  moduleFeature = ba-reader.findModuleFeature({feature_id}, moduleCode)
-
-  // Map wireframes to specification.uiWireframes[]
-  uiWireframes = moduleWireframes.map(wf => ({
-    "screen": wf.screen,
-    "section": wf.section,
-    "mockupFormat": wf.format,
-    "mockup": wf.content,
-    "description": wf.description || "",
-    "elements": wf.elements || [],
-    "actions": wf.actions || [],
-    "permissionsRequired": wf.permissionsRequired || [],
-    "componentMapping": wf.componentMapping || [],
-    "layout": wf.layout || null
-  }))
-
-  // Write to module feature.json (enriching specification section)
-  ba-writer.enrichSection({
-    featureId: moduleFeature.id,
-    section: "specification",
-    data: { uiWireframes: uiWireframes }
-  })
-```
-
-**Validation:** For each wireframe:
-- `screen` must be unique within module
-- `mockupFormat` must be "ascii" or "svg"
-- `mockup` content must not be empty
-- `componentMapping` array must have at least one entry
-- `layout` object must have `type` and `regions` if present
-
-#### Extract E2E flow diagrams
-
-IF `artifacts.e2eFlows` exists:
-
-```
-e2eFlows = artifacts.e2eFlows.map(flow => ({
-  "name": flow.name,
-  "modules": flow.modules.split(" → ").map(m => m.trim()),  // "OrderManagement → Invoicing" → ["OrderManagement", "Invoicing"]
-  "steps": flow.steps || [],
-  "diagram": flow.diagram,  // NEW: ASCII diagram preserved
-  "actors": flow.actors.split(", ").map(a => a.trim())
-}))
-
-// Merge with existing e2eFlows from consolidation.e2eFlows
-ba-writer.enrichSection({
-  featureId: {feature_id},
-  section: "consolidation",
-  data: { e2eFlows: e2eFlows }
-})
-```
-
-**Validation:** For each E2E flow:
-- `diagram` must not be empty if present
-- `modules` array must match modules defined in master feature.json
-- `steps` must have at least 2 entries (cross-module flow)
-
-#### Extract dependency graph (optional)
-
-IF `artifacts.dependencyGraph` exists:
-
-```
-dependencyGraph = {
-  "nodes": artifacts.dependencyGraph.nodes.map(n => ({
-    "id": n.id,
-    "label": n.label || n.id,
-    "type": n.type || "data-centric"
-  })),
-  "edges": artifacts.dependencyGraph.edges.map(e => ({
-    "from": e.from,
-    "to": e.to,
-    "description": e.description || ""
-  }))
-}
-
-// Write to master feature.json
-ba-writer.enrichSection({
-  featureId: {feature_id},
-  section: "decomposition",
-  data: { dependencyGraph: dependencyGraph }
-})
-```
-
-**Post-extraction summary:**
-
-```
-✓ Artefacts visuels extraits:
-  - Wireframes: {total_wireframe_count} across {module_count} modules
-  - E2E diagrams: {e2e_flow_count}
-  - Dependency graph: {node_count} nodes, {edge_count} edges
-```
-
-### 7. Resume de l'extraction
-
-Afficher un resume comparatif :
-```
-═══════════════════════════════════════════════════════════════
-  EXTRACTION TERMINEE - {application_name}
-═══════════════════════════════════════════════════════════════
-
-| Element                | Document client | Feature.json |
-|------------------------|----------------|--------------|
-| Probleme               | {oui/non}      | cadrage.problem |
-| Situation actuelle     | {oui/non}      | cadrage.asIs |
-| Vision                 | {oui/non}      | cadrage.toBe |
-| Parties prenantes      | {count}        | cadrage.stakeholders |
-| Perimetre (vital)      | {count}        | globalScope.mustHave |
-| Perimetre (important)  | {count}        | globalScope.shouldHave |
-| Perimetre (optionnel)  | {count}        | globalScope.couldHave |
-| Risques                | {count}        | cadrage.risks |
-| Criteres de reussite   | {count}        | acceptanceCriteria |
-| Domaines fonctionnels  | {count}        | modules |
-| Dependances            | {count}        | dependencyGraph.edges |
-| Cas d'utilisation      | {total}        | specification.useCases |
-| Regles metier          | {total}        | analysis.businessRules |
-| Entites                | {total}        | analysis.entities |
-| Parcours E2E           | {count}        | consolidation.e2eFlows |
-| Maquettes (wireframes) | {total}        | specification.uiWireframes[] |
-| Diagrammes E2E         | {count}        | consolidation.e2eFlows[].diagram |
-
-Fichiers generes :
-  - docs/business/{app}/business-analyse/v1.0/feature.json (master)
-  - docs/business/{app}/{module}/business-analyse/v1.0/feature.json (par module)
-
-Artefacts visuels preserves :
-  - Toutes les maquettes ASCII/SVG validees lors de la specification
-  - Tous les diagrammes E2E pour les flux cross-module
-  - Graphe de dependances entre modules
-
-═══════════════════════════════════════════════════════════════
-```
-
-### 8. Choix de la suite
-
-```
-question: "L'extraction est terminee. Que souhaitez-vous faire ?"
-header: "Suite"
-options:
-  - label: "Enrichir avec le questionnaire"
-    description: "Lancer le cadrage approfondi (step-01) pour completer l'analyse avec des questions detaillees"
-  - label: "Passer au handoff"
-    description: "Generer directement le plan de developpement (step-05)"
-  - label: "Terminer"
-    description: "L'extraction suffit, je reprendrai manuellement"
-```
-
-SI "Enrichir" → charger step-01-cadrage.md (les donnees existantes seront preservees)
-SI "Handoff" → charger step-05a-handoff.md
-SI "Terminer" → EXIT
-
----
-
-## FONCTIONS UTILITAIRES
-
-### toPascalCase(text)
-"gestion des commandes" → "GestionDesCommandes"
-"commande" → "Commande"
-
-### toCamelCase(text)
-"Numero de commande" → "numeroDeCommande"
-"Date" → "date"
-
-### computePriority(probability, impact)
-| probability | impact | priority |
-|------------|--------|----------|
-| high | high | critical |
-| high | medium | critical |
-| high | low | medium |
-| medium | high | critical |
-| medium | medium | medium |
-| medium | low | low |
-| low | high | medium |
-| low | medium | low |
-| low | low | low |
-
-### inferAction(ucName)
-Mots cles → action :
-- creer, ajouter, nouveau → create
-- modifier, editer, mettre a jour → update
-- supprimer, retirer, annuler → delete
-- consulter, voir, afficher, lister → read
-- valider, approuver, confirmer → approve
-- exporter, telecharger → export
-- importer, charger → import
-- defaut → read
-
----
-
-## VALIDATION
-
-Avant d'ecrire dans feature.json, verifier :
-- Chaque stakeholder a au minimum : role, function
-- Chaque use case a au minimum : name, actor
-- Chaque business rule a au minimum : name, statement
-- Chaque entite a au minimum : name
-- Les IDs sont uniques (pas de doublons UC, BR, RISK)
-- Les modules references dans les dependances existent
-
-SI une validation echoue → afficher l'erreur et demander correction.
-
----
-
-## GARANTIES
-
-- **Zero perte** : chaque champ saisi dans le document HTML se retrouve dans le feature.json
-- **Enrichissement** : les IDs, permissions et liens sont generes automatiquement
-- **Conformite** : le feature.json resultant est conforme au schema
-- **Reversibilite** : le JSON exporte original est conserve dans `metadata.sourceExport`