@atlashub/smartstack-cli 2.1.0 → 2.3.0

package/templates/skills/business-analyse/steps/step-01-analyse.md

@@ -0,0 +1,523 @@
+---
+name: step-01-analyse
+description: Merged Discovery + Analysis - Elicitation, business rules, entities, proactive suggestions
+next_step: steps/step-02-specify.md
+---
+
+## YOUR TASK:
+
+Execute combined discovery and analysis: elicit requirements using ULTRATHINK mode, formalize business rules and entities, and suggest complementary modules.
+
+> **ULTRATHINK MODE:**
+> - Consider ALL edge cases before formulating questions
+> - Challenge EVERY stakeholder assumption
+> - Anticipate UNEXPRESSED needs
+> - Validate completeness before proceeding
+> - DO NOT accept vague answers
+> - Extract IMPLICIT rules from discovery responses
+
+---
+
+## EXECUTION SEQUENCE:
+
+### 1. Read Current State
+
+Use **ba-reader** agent to read feature.json:
+- `feature_id`, `application_name`, `module_name`, `use_case`, `language`, `economy_mode`
+- Determine if delta mode (refactoring) or new feature
+
+Use **ba-writer** agent to update feature.json:
+- Set `metadata.steps.analyse.status = "in-progress"`
+
+**Language Config:**
+All AskUserQuestion calls must use `{language}` (default: fr).
+See `_shared.md` for language configuration.
+
+> **⚠️ BRANDING:** Never use "SmartStack" in user-facing communication.
+> Use "la plateforme", "l'application", or "le système" instead.
+
+---
+
+### 2. Determine Feature Type (for use_case = "new" or "micro")
+
+Analyze `feature.description` to classify:
+
+| Type | Keywords | Categories to Load |
+|------|----------|------------------|
+| **Data-centric** | management, CRUD, entity, data | 01, 02, 03, 04, 06, 11 |
+| **Integration** | API, sync, import, export, external | 01, 02, 03, 05, 06 |
+| **UI-centric** | screen, form, dashboard, interface | 01, 02, 03, 06, 07 |
+| **Workflow** | process, validation, workflow, steps | 01, 02, 03, 06, 09 |
+| **Reporting** | report, export, statistics, KPI | 01, 02, 03, 04, 08 |
+| **Full-module** | module, complete, feature | ALL |
+| **Micro** | (from -m flag) | 01, 02, 03, 06 (minimal) |
+
+Use **ba-writer** to set `metadata.featureType = {feature_type}`
+
+---
+
+### 3. Codebase Pre-Research (3 Phases)
+
+> **RULE: Explore BEFORE asking questions. Informed questions > generic questions.**
+
+**Phase 3a: MCP SmartStack (if available)**
+
+Call MCP tools (if not already done in step-00):
+- `mcp__smartstack__analyze_extension_points` → discover existing modules/entities
+- `mcp__smartstack__api_docs` → check existing API
+- `mcp__smartstack__validate_conventions` → validate module naming
+
+**Phase 3b: Parallel agents (if NOT economy_mode)**
+
+```
+Agent 1: "Search for existing domain entities in {application_name}.
+  List entities, attributes, relationships."
+
+Agent 2: "Search for integrations, services, SignalR, background jobs
+  that {module_name} might connect with."
+
+Agent 3: "Search for existing page patterns in {application_name}
+  (if UI-centric). List structures, components, navigation."
+```
+
+**Phase 3c: Economy mode**
+
+Use Glob/Grep directly:
+- Find 2-3 reference modules
+- Read key files to understand patterns
+- Extract domain context
+
+**Store findings:**
+Use **ba-writer** to add to `discovery.codebaseContext`:
+- Existing modules in {application_name}
+- Reusable entities and patterns
+- Potential integration points
+- RBAC patterns observed
+
+---
+
+### 4. Load Questionnaire Categories (Progressive)
+
+**ALWAYS load (core):**
+```
+questionnaire/01-context.md      # ~50 lines
+questionnaire/02-stakeholders.md # ~70 lines
+questionnaire/03-scope.md        # ~60 lines
+questionnaire/06-security.md     # ~70 lines
+```
+
+**Conditional (based on feature_type):**
+```
+Data-centric OR Full → questionnaire/04-data.md, 11-data-lifecycle.md
+Integration OR Full → questionnaire/05-integrations.md
+UI-centric OR Full → questionnaire/07-ui.md
+Reporting OR Critical → questionnaire/08-performance.md
+Workflow OR Constraints → questionnaire/09-constraints.md
+New module → questionnaire/12-migration.md, 13-cross-module.md
+```
+
+**Micro mode shortcut:**
+Load ONLY questionnaire/01-context.md (minimal 4 questions):
+- What entity/feature?
+- What fields/attributes?
+- What values/states?
+- Who can view/edit?
+- Any business rules?
+- Validation: correct summary?
+
+**Delta mode (refactoring):**
+Load only categories relevant to the CHANGE description.
+Skip categories already answered in previous version.
+
+---
+
+### 5. Interactive Elicitation
+
+> **RULE: Use `AskUserQuestion` for EVERY question batch. NEVER list questions as text.**
+> **RULE: Question field does NOT support markdown. Use direct output for summaries.**
+
+**Flow per category:**
+
+1. Load questionnaire file for the category
+2. Ask batches of max 4 questions via AskUserQuestion with predefined options
+3. Process answers → apply ULTRATHINK + 5 Elicitation Techniques (see `_shared.md`)
+4. If vague → follow-up with targeted probes
+5. After category: display summary as direct text output (supports markdown)
+6. Ask validation with SHORT question: "Is this summary correct?"
+7. If corrections needed → apply follow-ups
+8. Move to next category
+
+**ULTRATHINK checkpoints during elicitation:**
+- After Q1: If answer is solution-oriented → reframe to problem
+- After Q2: If only 1-2 stakeholder types → probe for hidden users
+- After Q3: If > 5 Must-Have → ask to prioritize implementation order
+- If answer is vague → apply Technique 3 (Concrete Scenario)
+- If any answer contains permission attributes → flag as RBAC violation
+
+**Reformulation loop (after each category):**
+
+Step 1: Display summary as direct text (supports markdown):
+```
+## Synthèse - {category_name}
+
+- **Point 1:** {summary}
+- **Point 2:** {summary}
+```
+
+Step 2: Ask validation with SHORT question via AskUserQuestion:
+```
+question: "Cette synthèse est-elle correcte ?"
+options: [
+  { label: "Correct" },
+  { label: "Partiellement" },
+  { label: "Incorrect" }
+]
+```
+
+- **Correct** → proceed to next category
+- **Partiellement** → ask: "Quelles corrections ?"
+- **Incorrect** → re-ask with refined questions
+
+---
+
+### 6. Business Rules Extraction (from discovery + ULTRATHINK)
+
+Scan all elicitation answers for implicit and explicit rules:
+
+**Sources to analyze:**
+- Scope constraints (category 03)
+- Data validations (category 04)
+- Security restrictions (category 06)
+- Process conditions from flow descriptions
+- Stakeholder-mentioned constraints
+
+**Rule categories:**
+| Category | Example | BR-ID Pattern |
+|----------|---------|---|
+| Validation | "Email must be unique" | BR-VAL-XXX |
+| Calculation | "Total = sum of lines" | BR-CALC-XXX |
+| Workflow | "Manager must approve > 1000$" | BR-WF-XXX |
+| Security | "Only admin can delete" | BR-SEC-XXX |
+| Data | "Created date is immutable" | BR-DATA-XXX |
+
+**Rule formalization:**
+
+For each identified rule, create:
+```json
+{
+  "id": "BR-{category}-NNN",
+  "name": "Rule name",
+  "category": "validation|calculation|workflow|security|data",
+  "statement": "IF {condition} THEN {result} ELSE {alternative}",
+  "priority": "must|should|could",
+  "conditions": ["condition 1", "condition 2"],
+  "examples": [
+    { "input": "example input", "expected": "example output" }
+  ],
+  "testability": "How to verify this rule"
+}
+```
+
+**ULTRATHINK checkpoint:**
+- Each rule is testable?
+- Rules don't contradict each other?
+- No rule is solution-oriented (HOW instead of WHAT)?
+- Priority aligns with scope (Must-Have → must, etc.)?
+
+Use **ba-writer** to add all rules to `analysis.businessRules[]`
+
+---
+
+### 7. Business Objectives Extraction
+
+From discovery context, formalize measurable objectives:
+
+```json
+{
+  "id": "OBJ-NNN",
+  "objective": "description",
+  "metric": "what to measure",
+  "target": "target value"
+}
+```
+
+Examples:
+- OBJ-001: Reduce manual data entry time by 50%
+- OBJ-002: Achieve 95% first-pass accuracy
+- OBJ-003: Enable 100% of stakeholders to access real-time KPIs
+
+Use **ba-writer** to add to `analysis.businessObjectives[]`
+
+---
+
+### 8. Entity Definition - Business View (NO technical fields)
+
+From data questions and scope, define entities:
+
+**CRITICAL RULES:**
+- Business attributes ONLY (NO Id, TenantId, CreatedBy, UpdatedBy, etc.)
+- NO role attributes (User.Role, User.IsAdmin, User.AccessLevel)
+- RBAC is separate (step-02)
+- Relationships: 1:1, 1:N, N:M
+
+**Per entity, document:**
+```json
+{
+  "name": "EntityName (PascalCase)",
+  "description": "Business description",
+  "businessAttributes": [
+    { "name": "field", "type": "string", "required": true, "description": "meaning" }
+  ],
+  "relationships": [
+    { "name": "RelationshipName", "cardinality": "1:N", "with": "OtherEntity" }
+  ]
+}
+```
+
+**ULTRATHINK checkpoint:**
+- All entities from discovery captured?
+- Relationships complete?
+- No orphan entities?
+- **NO RBAC CHECK:** No role/permission/access-level as attribute?
+
+If permission attributes detected → FLAG error: "RBAC violation detected in entity {name}. Roles belong in Permission Matrix (step-02), not data model."
+
+Use **ba-writer** to add to `analysis.entities[]`
+
+---
+
+### 9. Process Flow Modeling
+
+Model the main business flow:
+
+```
+Entry Points → [Decision Points] → [Actions/Validations] → Exit Points
+   ↓              ↓                      ↓                    ↓
+  Trigger      Link to BR-WF rules    Link to BR-VAL      Success/Failure
+```
+
+For each decision point, link to relevant BR-WF rules.
+Document alternative flows (error paths, exceptions).
+
+Example structure:
+```
+1. User submits request → BR-VAL-001 (validation)
+   ├─ Valid → BR-WF-001 (workflow: awaiting approval)
+   │  └─ Manager approves → BR-WF-002 (accept)
+   │     └─ Request processed
+   └─ Invalid → BR-VAL-002 (error: required field missing)
+      └─ User corrected
+```
+
+Use **ba-writer** to add to `analysis.processFlow` (text or ASCII diagram)
+
+---
+
+### 10. Integrations & Cross-Module Impact
+
+From discovery, identify:
+
+| System | Direction | Data | Frequency | Format |
+|--------|-----------|------|-----------|--------|
+| {system} | In/Out/Bi | {data} | Real-time/Batch | JSON/CSV/API |
+
+For each integration:
+- Data format expected
+- Error handling strategy
+- Fallback behavior
+
+Document cross-module dependencies:
+- Which existing entities are referenced?
+- Which modules depend on this module?
+
+Use **ba-writer** to add to `analysis.integrations[]` and `analysis.crossModuleImpact`
+
+---
+
+### 11. Proactive Suggestions (NEW - skip for micro mode)
+
+After scope and entities are defined:
+
+1. Load `patterns/suggestion-catalog.md` (if available)
+2. Match module type against catalog patterns
+3. Present via AskUserQuestion:
+
+```json
+{
+  "question": "Based on your {module} module, I suggest complementary additions. Which interest you?",
+  "header": "Suggestions",
+  "options": [
+    { "label": "{Suggestion 1}", "description": "{reason}" },
+    { "label": "{Suggestion 2}", "description": "{reason}" },
+    { "label": "None", "description": "No additional modules needed" }
+  ],
+  "multiSelect": true
+}
+```
+
+Examples (for each module type):
+- **Data-centric:** Bulk import, Audit trail, Export templates, Archive strategy
+- **Integration:** Error recovery, Health monitoring, Retry policy, Logging
+- **UI-centric:** Mobile-responsive design, Accessibility audit, Dark mode, Offline support
+- **Workflow:** Escalation rules, SLA tracking, Approval chains, Notifications
+- **Reporting:** Scheduled exports, Data freshness, Custom dashboards, Mobile reports
+
+For each accepted suggestion:
+```json
+{
+  "suggestion": "...",
+  "description": "...",
+  "acceptedStatus": true,
+  "impactOnTimeline": "{days if any}",
+  "linkedRules": ["BR-IDs affected"]
+}
+```
+
+Use **ba-writer** to add to `analysis.suggestions[]`
+
+---
+
+### 12. Risk Analysis
+
+Identify risks from elicitation answers (skip for micro mode):
+
+Ask via AskUserQuestion:
+
+```json
+{
+  "question": "Quels risques métier identifiez-vous ?",
+  "options": [
+    { "label": "Adoption", "description": "Users might not adopt the module" },
+    { "label": "Data quality", "description": "Migration of existing data problematic" },
+    { "label": "Process gaps", "description": "Current process is misunderstood or will change" },
+    { "label": "Dependencies", "description": "Depends on another module not ready" }
+  ],
+  "multiSelect": true
+}
+```
+
+For each identified risk, classify:
+
+| Probability | Impact | Priority |
+|---|---|---|
+| High | High | **Critical** — mitigation required |
+| High | Low | **Medium** — monitor |
+| Low | High | **Medium** — contingency plan |
+| Low | Low | **Low** — accept |
+
+Store each risk:
+```json
+{
+  "id": "RISK-NNN",
+  "type": "business|technical|organizational",
+  "description": "...",
+  "probability": "high|medium|low",
+  "impact": "high|medium|low",
+  "priority": "critical|medium|low",
+  "mitigation": "..."
+}
+```
+
+Use **ba-writer** to add to `discovery.risks[]`
+
+---
+
+### 13. Write to feature.json
+
+Use **ba-writer** agent to enrich:
+- `discovery` section: problem, asIs, toBe, trigger, stakeholders, scope, risks, codebaseContext, openQuestions
+- `analysis` section: objectives, businessRules, entities, processFlow, integrations, crossModuleImpact, dataLifecycle, suggestions
+- Update `metadata.steps.analyse.status = "completed"`
+- **Initialize changelog** with first entry:
+
+```json
+{
+  "changelog": [
+    {
+      "step": "step-01-analyse",
+      "timestamp": "2025-02-01T09:00:00Z",
+      "changes": [
+        "Discovery: {stakeholder_count} stakeholders, {scope_must} must-haves",
+        "Analysis: {br_count} business rules, {entity_count} entities, {obj_count} objectives",
+        "Suggestions: {accepted_count}/{total_count} accepted",
+        "Risks: {risk_count} identified ({critical_count} critical)"
+      ]
+    }
+  ]
+}
+```
+
+---
+
+### 14. Display Summary and Load Next Step
+
+**Display:**
+
+```
+ANALYSE - {feature_id}
+├── Status: analysed
+├── Feature Type: {feature_type}
+├── Stakeholders: {count}
+├── Scope: {must} Must, {should} Should, {could} Could
+├── Business Rules: {br_count}
+├── Business Objectives: {obj_count}
+├── Entities: {entity_count}
+├── Integrations: {integration_count}
+├── Risks: {risk_count} ({critical_count} critical)
+├── Suggestions: {accepted}/{total}
+├── feature.json: {location}
+└── Next: step-02-specify.md
+```
+
+Load next step:
+```
+Read and execute: steps/step-02-specify.md
+```
+
+---
+
+## OUTPUT FORMAT:
+
+This step enriches `feature.json` with:
+- `discovery` section: complete elicitation findings
+- `analysis` section: rules, objectives, entities, flows, integrations, suggestions
+- Status: draft → analysed
+
+**Context reduction strategy:**
+- Use feature.json as single source of truth
+- Load questionnaires progressively (max 150-200 lines at a time)
+- Use agents (ba-reader, ba-writer) to avoid re-reading
+
+---
+
+## ERROR HANDLING:
+
+**If user abandons mid-way:**
+1. Save partial analysis with answers collected
+2. Mark incomplete sections with "[INCOMPLETE]"
+3. Update status to "in-progress"
+4. Allow resume with same feature_id
+
+**If MCP unavailable:**
+1. Use Glob/Grep for codebase exploration
+2. Continue with discovery
+3. Note in codebaseContext: "MCP unavailable"
+
+**If business rules contradict:**
+1. Identify conflicting BR-IDs
+2. Ask user to resolve via AskUserQuestion
+3. Document resolution in rule notes
+
+**If permission paths detected in entities:**
+STOP and flag error: "RBAC violation in entity attributes. Roles must be in Permission Matrix (step-02)."
+
+**If micro mode and user provides complex requirements:**
+1. Warn: "Micro mode is for simple features. Consider full analysis mode."
+2. Allow upgrade to full mode
+3. Preserve micro answers in feature.json
+
+---
+
+## NEXT STEP:
+
+After completion, proceed to `steps/step-02-specify.md`