@atlashub/smartstack-cli 2.0.0 → 2.2.0

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

@@ -1,299 +0,0 @@
----
-name: step-02-analyse
-description: Analysis phase - BRD formalization with business rules
-next_step: steps/step-03-specify.md
----
-
-## YOUR TASK:
-
-Transform discovery findings into a formal Business Requirements Document (BRD).
-Identify and formalize all business rules with BR-XXX identifiers.
-
-> **ULTRATHINK MODE:**
-> - Extract IMPLICIT rules from discovery responses
-> - Challenge completeness of each rule
-> - Verify no rule contradicts another
-> - Ensure rules are testable
-
-## 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"
-
-**Read digest from previous step:**
-Read `{output_dir}/digest-01.md` for compressed context from previous step.
-**DO NOT read full output files** unless in resume mode (`-r`).
-
----
-
-### 2. Load BRD Template
-
-```
-Read: templates/tpl-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?
-- **RBAC CHECK:** No role/permission/access-level modeled as entity attribute?
-  - `User.Role`, `User.AccessLevel`, `User.IsAdmin` = **FORBIDDEN**
-  - Roles are SmartStack RBAC permission sets, not data model concepts
-  - If stakeholders described roles, they belong in the Permission Matrix (step-03), not here
-
----
-
-### 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/tpl-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 |
-```
-
----
-
-### 9b. Generate Context Digest
-
-**Write digest to:** `{output_dir}/digest-02.md`
-
-```markdown
-# Digest: Step 02 - Analyse
-
-## Changes
-- {output_dir}/2-business-requirements.md: BRD created
-
-## Decisions
-- {count} business objectives formalized
-- {count} business rules identified (categories: VAL, CALC, WF, SEC, DATA)
-
-## Findings
-- {count} entities with {count} total attributes
-- {count} integrations identified
-- Process flow: {summary of main flow}
-
-## State Updates
-| Variable | New Value |
-|----------|-----------|
-| br_count | {count} |
-| entity_count | {count} |
-| integration_count | {count} |
-
-## For Next Step
-- BR-IDs to trace: {list of BR-IDs}
-- Entities to specify: {list}
-- Permission paths needed for: {list of entities}
-```
-
----
-
-### 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:**
-
-| Field | Value |
-|-------|-------|
-| Step | ANALYSE |
-| Feature | {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 FORMAT:
-
-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)
-
-## ERROR HANDLING:
-
-**If discovery document is incomplete:**
-1. List missing sections
-2. Ask user: "Return to discovery to complete, or proceed with available data?"
-3. If proceeding: mark BRD sections with "[INCOMPLETE - based on partial discovery]"
-
-**If business rules contradict each other:**
-1. Identify conflicting rules (BR-XXX vs BR-YYY)
-2. Ask user to resolve contradiction via AskUserQuestion
-3. Document resolution in BRD
-
-## NEXT STEP:
-
-After completion, proceed to `steps/step-03-specify.md`

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

@@ -1,409 +0,0 @@
----
-name: step-03-specify
-description: Specification phase - FRD with use cases, requirements, permissions
-next_step: steps/step-04-validate.md
----
-
-## YOUR TASK:
-
-Create comprehensive Functional Requirements Document (FRD) with:
-- Use Cases (UC-XXX)
-- Functional Requirements (FR-XXX)
-- Permission matrix
-- UI wireframes
-- Gherkin scenarios
-
-> **ULTRATHINK MODE:**
-> - Each UC must be atomic and testable
-> - FR must trace back to BR
-> - Permissions must follow SmartStack convention
-> - No ambiguity in scenarios
-
-## 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"
-
-**Read digest from previous step:**
-Read `{output_dir}/digest-02.md` for compressed context from previous step.
-**DO NOT read full output files** unless in resume mode (`-r`).
-
----
-
-### 2. Load FRD Template
-
-```
-Read: templates/tpl-frd.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` |
-
----
-
-### 9b. Data Lifecycle & Cross-Module Specification (CONDITIONAL)
-
-**Load ONLY if categories 11-13 were collected in discovery.**
-
-#### If data lifecycle data collected (category 11):
-
-| Entity | Retention Period | Archive Strategy | GDPR Impact | Base Class |
-|--------|-----------------|-----------------|-------------|------------|
-| {entity} | {duration} | {Archive/Purge/Anonymize} | {Yes/No + detail} | {SoftDeletableEntity/AuditableEntity} |
-
-**State transitions:**
-
-| Entity | States | Immutable After |
-|--------|--------|-----------------|
-| {entity} | {Draft -> Active -> Archived -> Deleted} | {state or "None"} |
-
-#### If migration data collected (category 12):
-
-| Source | Format | Volume | Quality Issues | Strategy |
-|--------|--------|--------|----------------|----------|
-| {source} | {Excel/CSV/DB/API} | {volume} | {issues} | {Big-bang/Progressive/Parallel} |
-
-**Rollback plan:** {strategy from Q12.8}
-
-#### If cross-module impact collected (category 13):
-
-| Existing Module | Interaction Type | Shared Data | Impact on Existing |
-|-----------------|-----------------|-------------|-------------------|
-| {module} | {FK/Event/Query/Navigation} | {entities/data} | {None/Minor/Major} |
-
-**MediatR events to create:**
-
-| Event | Trigger | Consumers |
-|-------|---------|-----------|
-| {Entity}CreatedNotification | After create | {list of consuming modules} |
-
----
-
-### 10. Compile FRD Document
-
-Assemble complete FRD using template structure.
-
----
-
-### 10b. Generate Context Digest
-
-**Write digest to:** `{output_dir}/digest-03.md`
-
-```markdown
-# Digest: Step 03 - Specify
-
-## Changes
-- {output_dir}/3-functional-specification.md: FRD created
-
-## Decisions
-- {count} use cases defined
-- {count} functional requirements (Must: X, Should: Y, Could: Z)
-- Permission matrix: {count} permissions for {count} roles
-
-## Findings
-- Gherkin scenarios: {count}
-- i18n keys: {count}
-- UI wireframes: {count}
-
-## State Updates
-| Variable | New Value |
-|----------|-----------|
-| uc_count | {count} |
-| fr_count | {count} |
-| permission_count | {count} |
-| scenario_count | {count} |
-
-## For Next Step
-- Completeness checklist ready for validation
-- All BR->FR traces established
-- Permission matrix finalized
-```
-
----
-
-### 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:**
-
-| Field | Value |
-|-------|-------|
-| Step | SPECIFICATION |
-| Feature | {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 FORMAT:
-
-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)
-
-## ERROR HANDLING:
-
-**If permission path format is invalid:**
-1. Validate with MCP: `mcp__smartstack__validate_conventions`
-2. If MCP unavailable: validate manually against pattern `business.{app}.{module}.{action}`
-3. Fix and re-generate permission matrix
-
-**If BR has no corresponding FR:**
-1. Flag unmapped BR-IDs
-2. Create placeholder FR with "To be specified"
-3. Add to validation checklist for step-04
-
-## NEXT STEP:
-
-After completion, proceed to `steps/step-04-validate.md`