@atlashub/smartstack-cli 1.13.2 → 1.14.0

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

@@ -0,0 +1,243 @@
+---
+name: step-02-analyse
+description: Analysis phase - BRD formalization with business rules
+model: sonnet
+prev_step: steps/step-01-discover.md
+next_step: steps/step-03-specify.md
+---
+
+<objective>
+Transform discovery findings into a formal Business Requirements Document (BRD).
+Identify and formalize all business rules with BR-XXX identifiers.
+</objective>
+
+<ultrathink>
+ULTRATHINK MODE - Business Rule Formalization:
+- Extract IMPLICIT rules from discovery responses
+- Challenge completeness of each rule
+- Verify no rule contradicts another
+- Ensure rules are testable
+</ultrathink>
+
+## EXECUTION SEQUENCE
+
+### 1. Read Current State
+
+Read `{output_dir}/00-context.md` to restore state variables.
+Read `{output_dir}/1-discovery.md` for discovery findings.
+
+Update progress: `02-analyse` -> "In Progress"
+
+---
+
+### 2. Load BRD Template
+
+```
+Read: templates/frd-brd.md    # ~90 lines only (vs 477 lines full template)
+```
+
+This template contains ONLY the BRD structure, not FRD or Handoff.
+
+---
+
+### 3. Extract Business Objectives
+
+From discovery section 1 (Contexte Business), formalize:
+
+| ID | Objective | Metric | Target |
+|----|----------|----------|-------|
+| OBJ-001 | {objective} | {measurable KPI} | {target value} |
+| OBJ-002 | ... | ... | ... |
+
+**ULTRATHINK checkpoint:**
+- Each objective is measurable?
+- Target values are realistic?
+- Objectives align with stakeholder needs?
+
+---
+
+### 4. Identify Business Rules
+
+Scan discovery document for implicit and explicit rules:
+
+**Sources to analyze:**
+- Scope section (constraints)
+- Stakeholder needs (role-specific rules)
+- Data requirements (validation rules)
+- Process flows (workflow rules)
+
+**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 |
+
+---
+
+### 5. Formalize Each Business Rule
+
+For each identified rule, create detailed specification:
+
+```markdown
+#### BR-XXX: {Rule Name}
+
+**Statement:** {Clear, unambiguous statement}
+
+**Conditions:**
+- IF {condition A}
+- AND {condition B}
+- THEN {result}
+- ELSE {alternative result}
+
+**Examples:**
+| Input | Expected Output |
+|-------|-----------------|
+| {example input 1} | {expected output 1} |
+| {example input 2} | {expected output 2} |
+
+**Testability:** {How to verify this rule}
+```
+
+---
+
+### 6. Model Business Process
+
+Create process diagram for main flow:
+
+```
+┌─────────────┐     ┌─────────────┐     ┌─────────────┐
+│   Step 1    │────►│   Step 2    │────►│   Step 3    │
+│  {action}   │     │  {action}   │     │  {action}   │
+└─────────────┘     └─────────────┘     └─────────────┘
+      │                   │                   │
+      ▼                   ▼                   ▼
+   {actor}            {actor}            {actor}
+```
+
+Identify:
+- Entry points
+- Decision points (apply BR-WF rules)
+- Exit points
+- Alternative flows
+
+---
+
+### 7. Define Data Entities (Business View)
+
+**IMPORTANT: Business attributes only - NO technical types!**
+
+| Entity | Description | Cardinality |
+|--------|-------------|-------------|
+| {Entity} | {business description} | 1:N with {other} |
+
+| Entity | Attribute | Description | Required |
+|--------|-----------|-------------|----------|
+| {Entity} | {attribute} | {business meaning} | Yes/No |
+
+**ULTRATHINK checkpoint:**
+- All entities from discovery captured?
+- Relationships are complete?
+- No orphan entities?
+
+---
+
+### 8. Identify Integrations
+
+| System | Direction | Data | Frequency |
+|--------|-----------|------|-----------|
+| {system} | In/Out/Bi | {data} | Real-time/Batch |
+
+For each integration, note:
+- Data format expected
+- Error handling strategy
+- Fallback behavior
+
+---
+
+### 9. Compile BRD Document
+
+Assemble using `templates/frd-brd.md` structure:
+
+```markdown
+# BRD - {feature_id} {feature_description}
+
+> **Module:** business/{application_name}/{module_name}
+> **Version:** 1.0
+> **Based on:** 1-discovery.md v1.0
+
+## 1. Executive Summary
+{3-5 sentence synthesis}
+
+## 2. Business Objectives
+{OBJ table}
+
+## 3. Business Rules
+{BR summary table}
+
+### 3.1 Critical Rules Detail
+{BR-XXX detailed specs}
+
+## 4. Business Process
+{Process diagrams}
+
+## 5. Business Data
+{Entity tables - business view}
+
+## 6. Integrations
+{Integration table}
+
+---
+
+## Version History
+
+| Version | Date | Author | Changes |
+|---------|------|--------|---------|
+| 1.0 | {date} | BA | Initial creation |
+```
+
+---
+
+### 10. Save Output
+
+Write to: `{output_dir}/2-business-requirements.md`
+
+Update `00-context.md`:
+- Progress: `02-analyse` -> "Complete"
+- Add BR count to state
+
+---
+
+### 11. Display Summary and Load Next Step
+
+**Display:**
+```
+ANALYSE - {feature_id}
+├── Status: Complete
+├── Objectives: {OBJ count}
+├── Business Rules: {BR count}
+├── Entities: {entity count}
+├── Integrations: {integration count}
+├── Output: {output_dir}/2-business-requirements.md
+└── Next: step-03-specify (FRD + Use Cases)
+```
+
+**If NOT auto_mode:**
+Ask: "Proceed with functional specification?"
+
+**Load next step:**
+```
+Read and execute: steps/step-03-specify.md
+```
+
+---
+
+## OUTPUT
+
+This step produces:
+- `{output_dir}/2-business-requirements.md` (created)
+- `{output_dir}/00-context.md` (updated)
+
+Template loaded: **~90 lines** (vs 477 lines full file)

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

@@ -0,0 +1,317 @@
+---
+name: step-03-specify
+description: Specification phase - FRD with use cases, requirements, permissions
+model: sonnet
+prev_step: steps/step-02-analyse.md
+next_step: steps/step-04-validate.md
+---
+
+<objective>
+Create comprehensive Functional Requirements Document (FRD) with:
+- Use Cases (UC-XXX)
+- Functional Requirements (FR-XXX)
+- Permission matrix
+- UI wireframes
+- Gherkin scenarios
+</objective>
+
+<ultrathink>
+ULTRATHINK MODE - Specification:
+- Each UC must be atomic and testable
+- FR must trace back to BR
+- Permissions must follow SmartStack convention
+- No ambiguity in scenarios
+</ultrathink>
+
+## EXECUTION SEQUENCE
+
+### 1. Read Current State
+
+Read `{output_dir}/00-context.md` to restore state variables.
+Read `{output_dir}/2-business-requirements.md` for business rules.
+
+Update progress: `03-specify` -> "In Progress"
+
+---
+
+### 2. Load FRD Template
+
+```
+Read: templates/frd-spec.md    # ~150 lines (UC + FR + permissions sections)
+```
+
+This template contains ONLY the FRD structure.
+
+---
+
+### 3. Define Actors and Permissions
+
+From BRD stakeholders, map to system actors:
+
+| Actor | Description | Permission base |
+|-------|-------------|-----------------|
+| Admin | Full access | `business.{app}.{module}.*` |
+| Manager | Read + Create + Update | `business.{app}.{module}.read,create,update` |
+| User | Read + Create | `business.{app}.{module}.read,create` |
+| ReadOnly | View only | `business.{app}.{module}.read` |
+
+**Permission format:** `business.{application_name}.{module_name}.{action}`
+
+Actions:
+- `.read` - View data
+- `.create` - Create new entries
+- `.update` - Modify existing
+- `.delete` - Remove entries
+- `.export` - Export data
+- `.import` - Import data
+- `.admin` - Administrative functions
+
+---
+
+### 4. Create Use Cases
+
+For each major functionality, create UC:
+
+```markdown
+### UC-001: {Use Case Name}
+
+| Attribute | Value |
+|-----------|-------|
+| **ID** | UC-001 |
+| **Name** | {Name} |
+| **Primary Actor** | {Role} |
+| **Preconditions** | {required conditions} |
+| **Postconditions** | {final state} |
+| **Permission** | `business.{app}.{module}.{action}` |
+
+**Main Scenario:**
+1. The user {action}
+2. The system {response}
+3. The user {action}
+4. The system {response}
+
+**Alternative Scenarios:**
+
+| # | Condition | Steps |
+|---|-----------|-------|
+| 3a | {condition} | 3a.1 {action}, 3a.2 {action} |
+
+**Error Scenarios:**
+
+| # | Error | Message | Action |
+|---|-------|---------|--------|
+| E1 | {error} | {user message} | {behavior} |
+
+**Associated Rules:** BR-001, BR-002
+```
+
+**ULTRATHINK checkpoint:**
+- Each UC maps to at least one BR?
+- All actors from BRD have UCs?
+- Error scenarios complete?
+
+---
+
+### 5. Define Functional Requirements
+
+For each BR, create corresponding FR:
+
+| ID | Requirement | Linked UC | Priority |
+|----|-------------|-----------|----------|
+| FR-001 | The system MUST... | UC-001 | Must |
+| FR-002 | The system SHOULD... | UC-001 | Should |
+| FR-003 | The system COULD... | UC-002 | Could |
+
+**Detailed FR specification:**
+
+```markdown
+### FR-001: {Requirement Name}
+
+**Statement:** The system MUST {specific action}
+
+**Acceptance Criteria:**
+- [ ] {Measurable criterion 1}
+- [ ] {Measurable criterion 2}
+- [ ] {Measurable criterion 3}
+
+**Associated Rules:** BR-001, BR-002
+**Use Cases:** UC-001
+```
+
+**Priority mapping:**
+- Must = FR-0XX (000-099)
+- Should = FR-1XX (100-199)
+- Could = FR-2XX (200-299)
+
+---
+
+### 6. Design Permission Matrix
+
+**Role-Permission Matrix:**
+
+| Permission | Admin | Manager | User | ReadOnly |
+|------------|-------|---------|------|----------|
+| `business.{app}.{module}.read` | X | X | X | X |
+| `business.{app}.{module}.create` | X | X | X | - |
+| `business.{app}.{module}.update` | X | X | - | - |
+| `business.{app}.{module}.delete` | X | - | - | - |
+| `business.{app}.{module}.export` | X | X | - | - |
+
+**Endpoint-Permission Mapping:**
+
+| Endpoint | Method | Required Permission |
+|----------|--------|-------------------|
+| `/api/business/{module}` | GET | `.read` |
+| `/api/business/{module}` | POST | `.create` |
+| `/api/business/{module}/{id}` | GET | `.read` |
+| `/api/business/{module}/{id}` | PUT | `.update` |
+| `/api/business/{module}/{id}` | DELETE | `.delete` |
+
+---
+
+### 7. Create UI Wireframes
+
+**Main screen wireframe:**
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  [Logo]    {Module Name}                      [User] [Menu] │
+├─────────────────────────────────────────────────────────────┤
+│                                                             │
+│  ┌─────────────────────────────────────────────────────┐   │
+│  │ FILTERS                                              │   │
+│  │ [Field 1 ▼] [Field 2 ▼] [Search]                   │   │
+│  └─────────────────────────────────────────────────────┘   │
+│                                                             │
+│  ┌─────────────────────────────────────────────────────┐   │
+│  │ DATA TABLE                                           │   │
+│  │ ┌────────┬────────┬────────┬─────────┐              │   │
+│  │ │ Col 1  │ Col 2  │ Col 3  │ Actions │              │   │
+│  │ ├────────┼────────┼────────┼─────────┤              │   │
+│  │ │ data   │ data   │ data   │ [E] [D] │              │   │
+│  │ └────────┴────────┴────────┴─────────┘              │   │
+│  └─────────────────────────────────────────────────────┘   │
+│                                                             │
+│  [+ New] (if .create)                   [< Prev] [Next >]  │
+└─────────────────────────────────────────────────────────────┘
+```
+
+**UI Elements description:**
+
+| Element | Type | Behavior | Permission |
+|---------|------|----------|------------|
+| [+ New] | Button | Opens create modal | `.create` |
+| [E] | Icon | Opens edit modal | `.update` |
+| [D] | Icon | Confirm + delete | `.delete` |
+
+---
+
+### 8. Write Gherkin Scenarios
+
+```gherkin
+Feature: {feature_id} {feature_description}
+
+  Background:
+    Given the system is configured with test data
+    And the permission system is active
+
+  @permission @403
+  Scenario: User without permission cannot create
+    Given I am logged in as "user@test.com" with role "ReadOnly"
+    When I send POST to "/api/business/{module}"
+    Then the response status should be 403
+    And the response should contain "Permission denied"
+
+  @happy-path
+  Scenario: Admin creates new item
+    Given I am logged in as "admin@test.com" with role "Admin"
+    And I have permission "business.{app}.{module}.create"
+    When I send POST to "/api/business/{module}" with:
+      | field1 | value1 |
+      | field2 | value2 |
+    Then the response status should be 201
+    And the response should contain "id"
+
+  @validation
+  Scenario: Validation error on required field
+    Given I am logged in with permission "business.{app}.{module}.create"
+    When I send POST to "/api/business/{module}" with:
+      | field1 | |
+    Then the response status should be 400
+    And the response should contain "field1 is required"
+
+  @business-rule @BR-001
+  Scenario: {BR-001 scenario}
+    Given {precondition}
+    When {action}
+    Then {expected result per BR-001}
+```
+
+---
+
+### 9. Define Validations and Messages
+
+**Field validations:**
+
+| Field | Rule | Error Message (i18n key) |
+|-------|------|--------------------------|
+| {field} | Required | `{module}.errors.{field}Required` |
+| {field} | MaxLength(100) | `{module}.errors.{field}TooLong` |
+| email | Email format | `{module}.errors.invalidEmail` |
+
+**System messages:**
+
+| Code | Type | Message (i18n key) |
+|------|------|-------------------|
+| MSG-001 | Success | `{module}.messages.created` |
+| MSG-002 | Success | `{module}.messages.updated` |
+| MSG-003 | Success | `{module}.messages.deleted` |
+| MSG-004 | Error | `{module}.errors.notFound` |
+| MSG-005 | Error | `{module}.errors.permissionDenied` |
+
+---
+
+### 10. Compile FRD Document
+
+Assemble complete FRD using template structure.
+
+---
+
+### 11. Save Output
+
+Write to: `{output_dir}/3-functional-specification.md`
+
+Update `00-context.md`:
+- Progress: `03-specify` -> "Complete"
+- Add UC count, FR count, permission count
+
+---
+
+### 12. Display Summary and Load Next Step
+
+**Display:**
+```
+SPECIFICATION - {feature_id}
+├── Status: Complete
+├── Use Cases: {UC count}
+├── Requirements: {FR count} (Must: X, Should: Y, Could: Z)
+├── Permissions: {permission count}
+├── Gherkin scenarios: {scenario count}
+├── Output: {output_dir}/3-functional-specification.md
+└── Next: step-04-validate (Validation Gate)
+```
+
+**Load next step:**
+```
+Read and execute: steps/step-04-validate.md
+```
+
+---
+
+## OUTPUT
+
+This step produces:
+- `{output_dir}/3-functional-specification.md` (created)
+- `{output_dir}/00-context.md` (updated)
+
+Template loaded: **~150 lines** (vs 477 lines full file)