@atlashub/smartstack-cli 2.1.0 → 2.3.0

package/templates/skills/business-analyse/_shared.md

@@ -1,36 +1,85 @@
-# Business Analysis - Shared Functions (v2 - Progressive Loading)
+# Business Analysis - Shared Functions (v3 - JSON-First Progressive Loading)
 
 > **Ref:** This file contains common functions for all BA phases.
-> **Version:** 2.0 - Optimized for progressive loading
+> **Version:** 3.0 - JSON-First architecture with progressive loading
 
 ---
 
 ## Architecture Progressive
 
-Le skill BusinessAnalyse utilise le **chargement progressif** pour minimiser le contexte:
+The BusinessAnalyse skill uses **progressive loading** to minimize context:
 
 ```
-SKILL.md (entry point)
+SKILL.md (entry point) → routes to use case
     ↓
-steps/step-00-init.md (parse flags, create state)
+steps/step-00-init.md (parse flags, create feature.json via ba-writer)
     ↓
-steps/step-01-discover.md (charge questionnaire/XX.md on-demand)
+steps/step-01-analyse.md (merged discovery+BRD, loads questionnaire/*.md)
     ↓
-steps/step-02-analyse.md (charge templates/tpl-brd.md)
+steps/step-02-specify.md (FRD + use cases + permissions)
     ↓
-steps/step-03-specify.md (charge templates/tpl-frd.md)
+steps/step-03-validate.md (validation gate)
     ↓
-steps/step-04-validate.md (validation gate)
-    ↓
-steps/step-05-handoff.md (charge templates/tpl-handoff.md)
-    ↓
-steps/step-06-doc-html.md (charge react/*.md on-demand)
+steps/step-04-handoff.md (generates ralph prd.json)
 ```
 
+**No digest files needed** — each step reads/writes `feature.json` directly via `ba-writer` and `ba-reader` agents.
+
 **Benefit:** ~70% context reduction per phase
 
 ---
 
+## JSON-First Architecture
+
+All BA outputs are stored in a single `feature.json` file, enriched progressively:
+
+| Step | Section enriched | Status after |
+|------|-----------------|--------------|
+| 00-init | metadata | draft |
+| 01-analyse | discovery + analysis + suggestions | analysed |
+| 02-specify | specification | specified |
+| 03-validate | validation | approved |
+| 04-handoff | handoff | handed-off |
+
+**Agents:**
+- **ba-writer**: Writes/updates feature.json (create, enrichSection, updateStatus, createVersion)
+- **ba-reader**: Reads feature.json (findFeature, readSection, answerQuestion, getSummaryForSkill)
+
+**Schema:** `schemas/feature-schema.json`
+
+**Cross-references in JSON:**
+- `specification.useCases[].linkedRules` → `analysis.businessRules[].id`
+- `specification.functionalRequirements[].linkedUseCases` → `specification.useCases[].id`
+- `specification.functionalRequirements[].linkedRules` → `analysis.businessRules[].id`
+- `handoff.brToCodeMapping[].ruleId` → `analysis.businessRules[].id`
+
+---
+
+## Use Case Routing
+
+| Flag | Use Case | Workflow |
+|------|----------|---------|
+| (none) | New feature | step-00 → step-01 → step-02 → step-03 → step-04 |
+| `-q FEAT-ID "question"` | Question | ba-reader.answerQuestion → EXIT |
+| `-r FEAT-ID "change"` | Refactoring | ba-writer.createVersion → step-01 (delta) → step-02 → step-03 → step-04 |
+| `-m` | Micro-feature | step-00 (minimal) → step-01 (micro) → step-02 (minimal) → step-03 (auto) → step-04 (simplified) |
+
+### Delta Mode (Refactoring)
+- ba-reader loads existing feature.json
+- ba-writer creates new version folder (v{X.Y+1})
+- step-01 only asks questions about the CHANGE, not the entire module
+- step-02 only adds/modifies affected UCs, FRs, permissions
+- Existing data preserved, only delta applied
+
+### Micro Mode
+- Questions: entity, fields, values, who can change (4-6 questions max)
+- step-01: simplified analysis (no ULTRATHINK, no proactive suggestions)
+- step-02: minimal specification (1-2 UCs, standard CRUD)
+- step-03: auto-validation (structural check only)
+- step-04: simplified handoff
+
+---
+
 ## Business Context Validation
 
 ```
@@ -166,29 +215,21 @@ Route pattern : `/business/{application}/{module}/{section}`
 ## Feature Directory Structure
 
 ```
-.business-analyse/
-├── config.json                    # Global config
-└── business/
-    └── {application}/
-        └── modules/
-            └── {module}/
-                └── features/
-                    └── {FEAT-NNN}/
-                        ├── 00-context.md      # State persistence
-                        ├── 1-discovery.md
-                        ├── 2-business-requirements.md
-                        ├── 3-functional-specification.md
-                        ├── validation.json
-                        ├── 4-development-handoff.md
-                        └── tracking/
-                            ├── changes/
-                            │   └── CHANGE-NNN.md
-                            ├── bugs/
-                            ├── hotfixes/
-                            └── docs-manifest-entry.json
+docs/
+├── business/
+│   └── {application}/
+│       └── {module}/
+│           ├── business-analyse/
+│           │   ├── v1.0/
+│           │   │   └── feature.json
+│           │   └── v1.1/
+│           │       └── feature.json
+│           └── user-guide/          ← post-development (separate skill)
+│               └── v1.0/
+│                   └── guide.json
 ```
 
-**Ralph Loop Integration (generated by step-05):**
+**Ralph Loop Integration (generated by step-04):**
 
 ```
 .ralph/
@@ -198,7 +239,7 @@ Route pattern : `/business/{application}/{module}/{section}`
 └── reports/
 ```
 
-> **Note:** `.ralph/prd.json` is generated by step-05-handoff from the file mapping, business rules, and test requirements. It provides an atomic task list following the SmartStack layer order (Domain -> Application -> Infrastructure -> API -> Frontend -> i18n -> Tests -> Validation).
+> **Note:** `.ralph/prd.json` is generated by step-04-handoff from the feature.json mapping, business rules, and test requirements. It provides an atomic task list following the SmartStack layer order (Domain → Application → Infrastructure → API → Frontend → i18n → Tests → Validation).
 
 ---
 
@@ -219,12 +260,10 @@ generate_feature_id():
 | Step | Model | Reason |
 |------|-------|--------|
 | 00-init | Haiku | Quick structure setup |
-| 01-discover | **Opus** | ULTRATHINK elicitation |
-| 02-analyse | Sonnet | BRD modeling |
-| 03-specify | Sonnet | FRD + Use Cases |
-| 04-validate | Haiku | Binary gate |
-| 05-handoff | **Opus** | Zero-ambiguity prompt |
-| 06-doc-html | Sonnet | React + Context7 |
+| 01-analyse | **Opus** | ULTRATHINK merged discovery+BRD |
+| 02-specify | Sonnet | FRD + Use Cases |
+| 03-validate | Haiku | Binary gate |
+| 04-handoff | **Opus** | Zero-ambiguity prompt |
 
 ---
 
@@ -245,13 +284,19 @@ generate_feature_id():
 
 | Category | Questions | Batches |
 |----------|-----------|---------|
-| 01-context | Q1.1-Q1.8 | 2 calls (Q1.1-Q1.4 then Q1.5-Q1.8) |
-| 02-stakeholders | Q2.1-Q2.8 | 2 calls (Q2.1-Q2.4 then Q2.5-Q2.8) |
-| 03-scope | Q3.1-Q3.8 | 2 calls (Q3.1-Q3.4 then Q3.5-Q3.8) |
-| 04-data | Q4.1-Q4.8 | 2 calls (Q4.1-Q4.4 then Q4.5-Q4.8) |
-| 05-integrations | Q5.1-Q5.8 | 2 calls (Q5.1-Q5.4 then Q5.5-Q5.8) |
-| 06-security | Q6.1-Q6.8 | 2 calls (Q6.1-Q6.4 then Q6.5-Q6.8) |
-| 07-10 | Q7-Q10 | 1-2 calls each |
+| 01-context | Q1.1-Q1.4 | 1 call |
+| 02-stakeholders | Q2.1-Q2.8 | 2 calls |
+| 03-scope | Q3.1-Q3.8 | 2 calls |
+| 04-data | Q4.1-Q4.8 | 2 calls |
+| 05-integrations | Q5.1-Q5.8 | 2 calls |
+| 06-security | Q6.1-Q6.8 | 2 calls |
+| 07-ui | Q7.1-Q7.8 | 2 calls |
+| 08-performance | Q8.1-Q8.4 | 1 call |
+| 09-constraints | Q9.1-Q9.4 | 1 call |
+| 10-documentation | Q10.1-Q10.4 | 1 call |
+| 11-data-lifecycle | Q11.1-Q11.8 | 2 calls |
+| 12-migration | Q12.1-Q12.8 | 2 calls |
+| 13-cross-module | Q13.1-Q13.8 | 2 calls |
 
 ### AskUserQuestion Format
 
@@ -306,7 +351,7 @@ AskUserQuestion({
 
 ## Elicitation Techniques
 
-> **Loaded by:** step-01-discover (Opus ULTRATHINK)
+> **Loaded by:** step-01-analyse (Opus ULTRATHINK)
 > **Purpose:** Guide HOW to question, not just WHAT to ask.
 
 ### Technique 1: Solution → Problem Reframing
@@ -373,7 +418,7 @@ For every list answer, challenge completeness:
 
 ## ULTRATHINK
 
-Behavioral mode for critical phases (01, 02, 03, 05):
+Behavioral mode for critical phases (01, 02, 04):
 
 ```
 ULTRATHINK MODE:
@@ -394,7 +439,21 @@ DO NOT:
 
 ---
 
-## Context7 (Step 06)
+## Proactive Suggestions
+
+After scope definition in step-01, the skill suggests complementary modules/sections:
+
+1. Analyze feature type and scope from questionnaire answers
+2. Load `patterns/suggestion-catalog.md`
+3. Match against catalog patterns
+4. Present suggestions via AskUserQuestion (accept/reject per suggestion)
+5. Store in feature.json.suggestions[]
+
+Accepted suggestions become candidates for future /business-analyse runs.
+
+---
+
+## Context7 (Step 04)
 
 ```
 Prompt pattern:
@@ -441,53 +500,40 @@ Libraries:
 
 | Type | Path |
 |------|------|
-| Documentation | `web/smartstack-web/src/pages/docs/business/{app}/{module}/` |
+| BA Feature | `docs/business/{app}/{module}/business-analyse/v{X.Y}/feature.json` |
+| User Guide | `docs/business/{app}/{module}/user-guide/v{X.Y}/guide.json` |
 | i18n | `web/smartstack-web/src/i18n/locales/{lang}/` |
-| Route | `/docs/business/{app}/{module}` |
 
 ---
 
 ## State Persistence
 
-The `00-context.md` file persists state between steps:
-
-```markdown
-# Business Analysis: {{feature_id}}
+State is persisted in `feature.json.metadata` and `feature.json.metadata.steps`. Each step reads/writes via `ba-writer` and `ba-reader` agents.
 
-## Progress
-| Step | Status | Started | Completed |
-|------|--------|---------|-----------|
-| 00-init | Complete | ... | ... |
-| 01-discover | In Progress | ... | - |
-...
-
-## State Variables
-| Variable | Value |
-|----------|-------|
-| feature_id | FEAT-001 |
-| application_name | Sales |
-...
+```json
+{
+  "metadata": {
+    "featureId": "FEAT-001",
+    "status": "analysed",
+    "steps": {
+      "00-init": { "completed": "2025-02-01T10:00:00Z" },
+      "01-analyse": { "completed": "2025-02-01T11:30:00Z" },
+      "02-specify": { "inProgress": true }
+    }
+  }
+}
 ```
 
-**Read:** Each step starts by reading 00-context.md
-**Write:** Each step updates 00-context.md at the end
-
 ---
 
 ## Resume Workflow
 
 ```
-resume_workflow(task_id):
-  1. Search .business-analyse/ for matching feature
-  2. Read 00-context.md
-  3. Find last "Complete" step in Progress table
-  4. Return next step to load
-
-Example:
-  /business-analyse -r FEAT-001
-  → Reads .business-analyse/.../FEAT-001/00-context.md
-  → Finds "01-discover: Complete, 02-analyse: Pending"
-  → Loads step-02-analyse.md
+resume_workflow(feat_id):
+  1. ba-reader.findFeature(feat_id) → latest feature.json
+  2. Read feature.json.metadata.steps → find last completed step
+  3. Load next step file
+  4. If not found in docs/: fallback to .business-analyse/ (legacy)
 ```
 
 ---
@@ -496,9 +542,9 @@ Example:
 
 ```
 {STEP_NAME} - {feature_id}
-├── Status: {Complete/In Progress}
-├── Key metric: {value}
-├── Output: {file created}
+├── Status: {status in feature.json}
+├── Section enriched: {discovery|analysis|specification|validation|handoff}
+├── feature.json: {path}
 └── Next: {next step name}
 ```
 
@@ -512,7 +558,7 @@ Example:
 
 ### Configuration
 
-Le champ `language` dans `.business-analyse/config.json` définit la langue :
+Le champ `language` dans `feature.json.metadata.language` définit la langue :
 
 | Langue | Code | Défaut |
 |--------|------|--------|
@@ -528,14 +574,14 @@ Le champ `language` dans `.business-analyse/config.json` définit la langue :
 | Questions `AskUserQuestion` (labels, descriptions, options) | **OUI** — toujours dans `{language}` |
 | Reformulations et résumés de catégorie | **OUI** — toujours dans `{language}` |
 | Relances et follow-ups (Elicitation Guide) | **OUI** — traduire les probes à la volée |
-| Documents générés (discovery, BRD, FRD, handoff) | **OUI** — rédigés dans `{language}` |
+| Documents générés (discovery, analysis, specification, handoff) | **OUI** — rédigés dans `{language}` |
 | Référence technique interne (patterns, architecture) | NON — reste en langue du fichier |
 | Noms de code (entités, permissions, paths) | NON — toujours en anglais (convention plateforme) |
 
 ### Règle
 
 ```
-1. Lire {language} depuis 00-context.md (défaut: "fr")
+1. Lire {language} depuis feature.json.metadata.language (défaut: "fr")
 2. Adapter TOUTE communication AskUserQuestion dans {language}
 3. Les exemples de probes/relances dans les questionnaires sont en français
    → Si {language} ≠ "fr", les traduire à la volée
@@ -563,62 +609,6 @@ Le champ `language` dans `.business-analyse/config.json` définit la langue :
 
 ---
 
-## Progressive Loading Benefits
-
-| Aspect | Before | After | Gain |
-|--------|--------|-------|------|
-| Questionnaire | 283 L (all) | 40-60 L (per category) | ~75% |
-| FRD Templates | 477 L (all) | 80-150 L (per type) | ~70% |
-| React Templates | 580 L (all) | 250-350 L (per need) | ~45% |
-| **Total/step** | ~1,340 L | ~300-400 L | **~70%** |
-
----
-
-## Context Digest (Between Steps)
-
-Each step produces a compressed digest file (max 50 lines) at completion to reduce token usage in the next step.
-
-**File naming:** `{output_dir}/digest-{step_number}.md` (e.g., `digest-01.md`, `digest-02.md`)
-
-| Section | Max Lines | Content |
-|---------|-----------|---------|
-| Changes | 10 | Files modified with brief description |
-| Decisions | 10 | Key architectural decisions |
-| Findings | 10 | Issues found, patterns identified |
-| State | 5 | Updated state variables |
-| Next | 5 | What the next step needs to know |
-
-**Protocol:**
-- **Generate:** Each step writes `digest-{step_number}.md` before completing
-- **Read:** Next step reads `digest-{prev_step_number}.md` instead of full output files
-- **Resume mode (`-r`):** Reads full output files directly (digest is for progressive loading only)
-- **Step-00:** Does not read a digest (it is the first step)
-- **Step-00:** Generates `digest-00.md` with initial state variables and configuration
-
-**Template:**
-```markdown
-# Digest: Step {NN} - {Step Name}
-
-## Changes
-- {file}: {brief description}
-
-## Decisions
-- {decision and rationale}
-
-## Findings
-- {finding}
-
-## State Updates
-| Variable | New Value |
-|----------|-----------|
-| {var} | {value} |
-
-## For Next Step
-- {what the next step needs to know}
-```
-
----
-
 ## Support
 
 Contact: **support@atlshub.ch**