@atlashub/smartstack-cli 2.1.0 → 2.2.0

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

@@ -0,0 +1,833 @@
+# Step 02: Specification
+
+> **Version:** 3.0.0
+> **Name:** step-02-specify
+> **Next step:** steps/step-03-validate.md
+> **Purpose:** Enrich feature.json with detailed specification section (use cases, functional requirements, actors, permissions, wireframes, scenarios)
+> **Input:** feature.json (scope, analysis sections populated)
+> **Output:** feature.json.specification enriched + status: "specified"
+
+---
+
+## 1. Introduction
+
+This step transforms the analysis from **discovery** into detailed **specifications**. You will:
+
+1. **Define actors and permissions** - Map stakeholder roles to system actors and RBAC permissions
+2. **Create use cases** - Model user interactions with UC-XXX identifiers
+3. **Define functional requirements** - Specify what the system must do (FR-XXX format)
+4. **Design permission matrix** - Map actors × resources × operations
+5. **Plan navigation & SeedData** - Design UI hierarchy and mandatory reference data
+6. **Sketch UI wireframes** - Visual representation of key screens
+7. **Write Gherkin scenarios** - Acceptance criteria in BDD format
+8. **Define validations & messages** - Business rules for data quality
+9. **Model data lifecycle** - Creation, updates, deletions, archiving patterns
+
+---
+
+## 2. Mode Support
+
+### Standard Mode
+Execute all sections in full detail.
+
+### Delta Mode
+IF use_case = refactoring:
+- Only add/modify use cases, functional requirements, and permissions for **affected features**
+- Keep existing UCs, FRs, and permissions intact (DO NOT regenerate complete matrix)
+- Mark affected sections with `delta: true` in specification
+- Preserve backwards compatibility
+
+### Micro Mode
+IF use_case = micro:
+- Generate **minimal spec** for MVP
+- Use cases: 1-2 only (typically Create + Read, or List + Detail)
+- Functional requirements: standard CRUD only (no advanced features)
+- Permission matrix: default 4-role (Admin, Manager, User, Guest)
+- Gherkin scenarios: basic happy path + one error case
+- No navigation hierarchy complexity
+- Minimal SeedData (only essential lookups)
+
+---
+
+## 3. Section 1: Define Actors & Permissions
+
+### 3.1 Map Stakeholder Roles to System Actors
+
+From `feature.json.discovery.stakeholders[]`, create an **actors** section in specification:
+
+```json
+{
+  "specification": {
+    "actors": [
+      {
+        "id": "ACTOR-001",
+        "role": "Admin",
+        "description": "System administrator with full control",
+        "canDelegate": true,
+        "basePermissions": ["Read", "Create", "Update", "Delete"]
+      },
+      {
+        "id": "ACTOR-002",
+        "role": "Manager",
+        "description": "Module manager with approval authority",
+        "canDelegate": false,
+        "basePermissions": ["Read", "Create", "Update"]
+      },
+      {
+        "id": "ACTOR-003",
+        "role": "User",
+        "description": "Standard user for daily operations",
+        "canDelegate": false,
+        "basePermissions": ["Read", "Create"]
+      },
+      {
+        "id": "ACTOR-004",
+        "role": "Guest",
+        "description": "External user with minimal access",
+        "canDelegate": false,
+        "basePermissions": ["Read"]
+      }
+    ]
+  }
+}
+```
+
+### 3.2 Define Permission Categories
+
+For each actor, enumerate:
+
+| Category | Examples | Notes |
+|----------|----------|-------|
+| **Read** | View list, View detail, Search, Export | Includes all retrieval operations |
+| **Create** | Add new record, Bulk import | Creation with initial state |
+| **Update** | Edit fields, Change status, Reassign | Update including state transitions |
+| **Delete** | Hard delete, Soft delete/Archive | Deletion or data removal |
+| **Approve** | Approve changes, Reject submissions | Workflow decisions |
+| **Delegate** | Assign task to another user | Transfer responsibility |
+| **Execute** | Trigger workflow, Process batch | Special actions |
+
+---
+
+## 4. Section 2: Create Use Cases (UC-XXX)
+
+### 4.1 Format & Structure
+
+For each major user interaction, create a use case:
+
+```markdown
+### UC-001: List [Resource] by [Criteria]
+
+| Field | Value |
+|-------|-------|
+| **ID** | UC-001 |
+| **Title** | List [Module] by [Criteria] |
+| **Actor(s)** | User, Manager |
+| **Trigger** | User navigates to [Module] menu |
+| **Precondition** | User is authenticated and has Read permission |
+| **Main Flow** | 1. System loads records from database filtered by [criteria] \| 2. Display paginated results with [fields] \| 3. User can sort/filter further |
+| **Alternative Flow** | No records: Show empty state with message; User cancels: Return to previous screen |
+| **Postcondition** | List displayed; User can select record for detail view |
+| **Linked Rules** | BR-001, BR-003 |
+
+```
+
+### 4.2 Use Case Categories
+
+Organize around resource operations:
+
+| UC Type | Examples | Count |
+|---------|----------|-------|
+| **List/Search** | List Orders, Search Customers, Find Products | 1 per resource |
+| **Create** | Create Order, Add Customer, Register Employee | 1 per resource |
+| **Read Detail** | View Order details, Customer profile | 1 per resource |
+| **Update** | Edit Order, Modify Customer address | 1 per resource |
+| **Delete/Archive** | Cancel Order, Archive Customer | 0-1 per resource |
+| **Bulk Operations** | Bulk Import Orders, Export Customers | 0-1 per resource |
+| **Workflow** | Approve Order, Escalate Ticket | 1 per workflow |
+| **Reports** | Order Summary, Customer Analysis | 0-1 per module |
+
+**Micro mode:** Limit to UC-001 (List) and UC-002 (Create), or UC-001 (List) and UC-002 (Detail).
+
+### 4.3 Link to Business Rules
+
+Each UC's "Linked Rules" field references `analysis.businessRules[].id`:
+
+```json
+{
+  "useCases": [
+    {
+      "id": "UC-001",
+      "linkedRules": ["BR-001", "BR-003"]
+    }
+  ]
+}
+```
+
+---
+
+## 5. Section 3: Define Functional Requirements (FR-XXX)
+
+### 5.1 Format & Priorities
+
+For each capability, create an FR:
+
+```json
+{
+  "functionalRequirements": [
+    {
+      "id": "FR-001",
+      "title": "Display [Resource] List",
+      "description": "System shall display paginated list of [resources] with sortable/filterable columns",
+      "priority": "MUST",
+      "actor": "User",
+      "linkedRules": ["BR-001"],
+      "acceptance": [
+        "List loads within 2 seconds",
+        "Pagination supports 10/25/50 items per page",
+        "User can sort by any column",
+        "User can filter by [field1], [field2]"
+      ]
+    },
+    {
+      "id": "FR-002",
+      "title": "Create [Resource] with Validation",
+      "description": "System shall accept new [resource] creation with mandatory field validation",
+      "priority": "MUST",
+      "actor": "User",
+      "linkedRules": ["BR-002", "BR-003"],
+      "acceptance": [
+        "All mandatory fields enforced on form",
+        "Validation messages appear inline",
+        "Submit button disabled until valid",
+        "Success message on creation"
+      ]
+    }
+  ]
+}
+```
+
+### 5.2 Priority Mapping
+
+| Priority | MOSCOW | Impact | Scheduling |
+|----------|--------|--------|-----------|
+| **MUST** | M (Must have) | Critical to MVP | Sprint N |
+| **SHOULD** | S (Should have) | High value, deferrable | Sprint N+1 |
+| **COULD** | C (Could have) | Nice-to-have | Backlog |
+| **WONT** | W (Won't have this time) | Out of scope | Future |
+
+**Micro mode:** All FRs have priority MUST (focus only on essential CRUD).
+
+### 5.3 FR Anatomy
+
+Each FR includes:
+- **id:** FR-NNN (sequential)
+- **title:** [Verb] [Object] [Qualifier]
+- **description:** What the system shall do
+- **priority:** MUST/SHOULD/COULD/WONT
+- **actor:** Which actor initiates
+- **linkedRules:** References to BR-XXX identifiers
+- **acceptance:** Testable acceptance criteria
+
+---
+
+## 6. Section 4: Permission Matrix & Data Model
+
+### 6.1 RBAC Matrix (Actors × Resources × Operations)
+
+Create a permission matrix for each resource:
+
+```json
+{
+  "permissionMatrix": [
+    {
+      "resource": "Order",
+      "operations": [
+        {
+          "op": "Read",
+          "Admin": true,
+          "Manager": true,
+          "User": true,
+          "Guest": false
+        },
+        {
+          "op": "Create",
+          "Admin": true,
+          "Manager": true,
+          "User": true,
+          "Guest": false
+        },
+        {
+          "op": "Update",
+          "Admin": true,
+          "Manager": true,
+          "User": false,
+          "Guest": false
+        },
+        {
+          "op": "Delete",
+          "Admin": true,
+          "Manager": false,
+          "User": false,
+          "Guest": false
+        }
+      ]
+    }
+  ]
+}
+```
+
+**Micro mode:** 4-role matrix only (Admin, Manager, User, Guest).
+
+### 6.2 Data Model Entities
+
+Define main entities and relationships:
+
+```json
+{
+  "entities": [
+    {
+      "name": "Order",
+      "pluralName": "Orders",
+      "description": "Purchase order entity",
+      "fields": [
+        {
+          "name": "id",
+          "type": "int",
+          "required": true,
+          "key": "primary"
+        },
+        {
+          "name": "orderNumber",
+          "type": "string",
+          "required": true,
+          "unique": true,
+          "length": 20
+        },
+        {
+          "name": "orderDate",
+          "type": "datetime",
+          "required": true
+        },
+        {
+          "name": "status",
+          "type": "enum",
+          "values": ["Draft", "Submitted", "Approved", "Shipped", "Delivered", "Cancelled"],
+          "default": "Draft"
+        }
+      ]
+    }
+  ]
+}
+```
+
+### 6.3 Navigation Hierarchy & UI Structure
+
+**CRITICAL: Define 5 Mandatory SeedData Tables**
+
+The navigation structure implies these mandatory SeedData tables:
+
+```json
+{
+  "navigationHierarchy": [
+    {
+      "level": 1,
+      "menuItem": "Module Name",
+      "icon": "icon-module",
+      "route": "/module",
+      "children": [
+        {
+          "level": 2,
+          "menuItem": "List [Resource]",
+          "route": "/module/list",
+          "seedDataRequired": [
+            "Module_Status (SeedData)",
+            "Module_Priority (SeedData)",
+            "Module_Category (SeedData)",
+            "Module_Type (SeedData)",
+            "Module_Department (SeedData)"
+          ]
+        },
+        {
+          "level": 2,
+          "menuItem": "Create [Resource]",
+          "route": "/module/create"
+        },
+        {
+          "level": 2,
+          "menuItem": "Reports",
+          "route": "/module/reports",
+          "children": [
+            {
+              "level": 3,
+              "menuItem": "Daily Summary",
+              "route": "/module/reports/daily"
+            }
+          ]
+        }
+      ]
+    }
+  ]
+}
+```
+
+**5 Mandatory SeedData Tables:**
+
+1. **Module_Status** - Record statuses (Draft, Approved, Published, Archived)
+2. **Module_Priority** - Priority levels (High, Medium, Low)
+3. **Module_Category** - Classification categories
+4. **Module_Type** - Resource subtypes or classifications
+5. **Module_Department** - Organizational units for filtering/access control
+
+These tables are:
+- Created in migrations before module features
+- Seeded with initial values (5-10 rows each)
+- Used in dropdowns and status filters throughout the UI
+- Referenced in validation and permission checks
+
+**Micro mode:** Minimal: Status and Category only. Skip Priority, Type, Department.
+
+---
+
+## 7. Section 5: UI Wireframes
+
+### 7.1 Key Screens
+
+For each major UC, sketch wireframe structure:
+
+```markdown
+### Wireframe WF-001: List [Resource]
+
+**Location:** `/module/list`
+
+**Layout:**
+```
+┌─────────────────────────────────────────┐
+│ Module > List [Resource]                │
+├─────────────────────────────────────────┤
+│ [Search] [Filter ▼] [Add New]          │
+├─────────────────────────────────────────┤
+│ ┌─────┬──────────┬────┬──────┐        │
+│ │ ID  │ Name     │... │ Action│        │
+│ ├─────┼──────────┼────┼──────┤        │
+│ │ 001 │ Item 1   │... │ Edit  │        │
+│ │ 002 │ Item 2   │... │ [⋮]   │        │
+│ └─────┴──────────┴────┴──────┘        │
+│                                         │
+│ Page 1 of 10 [◀] [1][2][3]... [▶]     │
+└─────────────────────────────────────────┘
+```
+
+**Components:**
+- Header with breadcrumb
+- Filter bar (by Status, Category, etc.)
+- Sortable data table with [fields]
+- Row actions: Edit, View, Delete (context menu)
+- Pagination controls
+- Empty state: "No [resources] found"
+
+**Responsive:** Full width on desktop, card view on mobile.
+```
+
+### 7.2 Form Validation UI
+
+For Create/Update screens:
+
+```markdown
+### Wireframe WF-002: Create [Resource]
+
+**Location:** `/module/create`
+
+**Form Fields:**
+```
+Field Name (required) *
+┌──────────────────────────┐
+│ [text input]             │ ✓
+└──────────────────────────┘
+Help text: [guidance]
+
+Status (required) *
+┌──────────────────────────┐
+│ [Draft ▼]                │
+└──────────────────────────┘
+
+[Cancel] [Save]
+```
+
+**Validations:**
+- Field Name: required, max 100 chars, no special characters (inline validation)
+- Status: required, dropdown only (no free text)
+- On submit: If invalid, highlight fields and show error messages above form
+- On success: Show success toast and navigate to detail view
+```
+
+---
+
+## 8. Section 6: Gherkin Scenarios (BDD)
+
+### 8.1 Feature Definition
+
+Write acceptance criteria in Gherkin format:
+
+```gherkin
+Feature: Order Management - List Orders
+  As a User
+  I want to view a paginated list of orders
+  So that I can find and manage orders efficiently
+
+  Scenario: User views default order list
+    Given I am logged in as a User
+    And I have Read permission on Orders
+    When I navigate to /orders
+    Then I should see the order list
+    And results should be sorted by OrderDate descending
+    And page size should default to 25 items
+    And I should see pagination controls
+
+  Scenario: User filters orders by status
+    Given I am on the order list page
+    And there are orders with different statuses
+    When I select "Approved" from Status filter
+    And I click Apply
+    Then only Approved orders should be displayed
+    And the filter should remain active on the page
+
+  Scenario: User searches for specific order
+    Given I am on the order list page
+    When I enter "ORD-001" in the search box
+    And I press Enter
+    Then only matching orders should be displayed
+    And search term should appear in the search box
+
+  Scenario: Empty state when no orders exist
+    Given I am on the order list page
+    And no orders exist in the system
+    Then I should see "No orders found"
+    And I should see "Create New Order" button
+    And pagination should not be visible
+```
+
+**Gherkin Rules:**
+- **Feature:** Module-level behavior
+- **Scenario:** Individual test case (happy path or alternative)
+- **Given:** Initial state/preconditions
+- **When:** User action
+- **Then:** Expected outcome
+- **And:** Additional steps in same context
+
+**Micro mode:** 2 scenarios max: happy path (List works) + one error case (empty state, validation failure).
+
+### 8.2 Scenario Categories
+
+| Category | Count | Examples |
+|----------|-------|----------|
+| **Happy Path** | 1 per UC | Normal operation succeeds |
+| **Alternative Flows** | 1-2 per UC | Empty state, no permission, etc. |
+| **Validation** | 1 per form | Invalid input rejected with message |
+| **Edge Cases** | 0-1 per UC | Boundary values, special characters |
+| **Error Handling** | 1 per UC | Server error, network failure |
+
+---
+
+## 9. Section 7: Validations & Business Messages
+
+### 9.1 Field Validations
+
+For each input field, specify validation rules:
+
+```json
+{
+  "validations": [
+    {
+      "fieldName": "OrderNumber",
+      "rules": [
+        {
+          "type": "required",
+          "message": "Order number is required"
+        },
+        {
+          "type": "unique",
+          "scope": "Order",
+          "message": "This order number already exists"
+        },
+        {
+          "type": "pattern",
+          "pattern": "^ORD-\\d{6}$",
+          "message": "Format must be ORD-XXXXXX (e.g., ORD-001234)"
+        },
+        {
+          "type": "maxLength",
+          "maxLength": 20,
+          "message": "Order number cannot exceed 20 characters"
+        }
+      ]
+    },
+    {
+      "fieldName": "OrderDate",
+      "rules": [
+        {
+          "type": "required",
+          "message": "Order date is required"
+        },
+        {
+          "type": "notFuture",
+          "message": "Order date cannot be in the future"
+        }
+      ]
+    }
+  ]
+}
+```
+
+### 9.2 Business Messages
+
+Define user-facing messages for operations:
+
+```json
+{
+  "messages": [
+    {
+      "code": "ORDER_CREATED_SUCCESS",
+      "type": "success",
+      "title": "Order Created",
+      "message": "Order {orderNumber} was created successfully.",
+      "i18nKey": "orders.messages.createdSuccess"
+    },
+    {
+      "code": "ORDER_CREATION_FAILED",
+      "type": "error",
+      "title": "Creation Failed",
+      "message": "Unable to create order. Please check your input and try again.",
+      "i18nKey": "orders.messages.creationFailed"
+    },
+    {
+      "code": "ORDER_NOT_FOUND",
+      "type": "error",
+      "title": "Not Found",
+      "message": "Order {id} does not exist.",
+      "i18nKey": "orders.messages.notFound"
+    },
+    {
+      "code": "PERMISSION_DENIED",
+      "type": "error",
+      "title": "Access Denied",
+      "message": "You do not have permission to {action} this order.",
+      "i18nKey": "common.messages.permissionDenied"
+    }
+  ]
+}
+```
+
+---
+
+## 10. Section 8: Data Lifecycle & Cross-Module Patterns
+
+### 10.1 Entity Lifecycle States
+
+Define state transitions for key entities:
+
+```json
+{
+  "lifeCycles": [
+    {
+      "entity": "Order",
+      "states": [
+        {
+          "id": "Draft",
+          "displayName": "Draft",
+          "description": "Order created but not yet submitted",
+          "allowedTransitions": ["Submitted", "Cancelled"],
+          "visibility": "Creator only"
+        },
+        {
+          "id": "Submitted",
+          "displayName": "Submitted for Review",
+          "description": "Order awaiting approval",
+          "allowedTransitions": ["Approved", "Rejected", "Cancelled"],
+          "visibility": "Creator + Manager",
+          "requiresApproval": true
+        },
+        {
+          "id": "Approved",
+          "displayName": "Approved",
+          "description": "Order approved and ready for fulfillment",
+          "allowedTransitions": ["Shipped", "Cancelled"],
+          "visibility": "All",
+          "triggerAction": "CreateFulfillmentTask"
+        },
+        {
+          "id": "Shipped",
+          "displayName": "Shipped",
+          "description": "Order dispatched to customer",
+          "allowedTransitions": ["Delivered", "Cancelled"],
+          "visibility": "All"
+        },
+        {
+          "id": "Delivered",
+          "displayName": "Delivered",
+          "description": "Order received by customer",
+          "allowedTransitions": ["Archived"],
+          "visibility": "All",
+          "isTerminal": true
+        },
+        {
+          "id": "Cancelled",
+          "displayName": "Cancelled",
+          "description": "Order cancelled",
+          "allowedTransitions": [],
+          "visibility": "All",
+          "isTerminal": true
+        }
+      ]
+    }
+  ]
+}
+```
+
+### 10.2 Cross-Module Dependencies
+
+Document how this module interacts with others:
+
+```json
+{
+  "crossModuleDependencies": [
+    {
+      "module": "Orders",
+      "dependsOn": "Customers",
+      "relationship": "Foreign key: Order.CustomerId → Customer.Id",
+      "synchronization": "Order.CustomerName auto-updates when Customer.Name changes",
+      "validation": "CustomerId must exist in Customers table",
+      "cascadeDelete": false
+    },
+    {
+      "module": "Orders",
+      "dependsOn": "Inventory",
+      "relationship": "Order creates InventoryMovement records",
+      "synchronization": "When Order status = Shipped, Inventory.OnHand decreases",
+      "validation": "Order cannot be approved if inventory insufficient",
+      "cascadeDelete": false
+    }
+  ]
+}
+```
+
+### 10.3 Audit & Archival
+
+Document data retention and auditing:
+
+```json
+{
+  "auditingPolicy": {
+    "enabled": true,
+    "trackFields": ["OrderNumber", "Status", "OrderDate", "TotalAmount"],
+    "retentionDays": 2555,
+    "archivalRule": "Orders older than 7 years are archived to cold storage"
+  },
+  "archivalPolicy": {
+    "enabled": true,
+    "archiveAfterDays": 2555,
+    "archiveLocation": "Archive_Orders table",
+    "restoreCapability": true
+  }
+}
+```
+
+---
+
+## 11. Execution Workflow
+
+### 11.1 Information Gathering
+
+1. **Load feature.json** via `ba-reader`:
+   - feature.json.scope.* - User goals and constraints
+   - feature.json.analysis.* - Business rules, stakeholder roles
+
+2. **Clarify with user:**
+   - Confirm actor roles and permission levels
+   - Validate use case scope (too many? combine?)
+   - Confirm resource state transitions
+   - Verify SeedData needs
+
+### 11.2 Specification Generation
+
+1. **Define actors** - Map to system roles with base permissions
+2. **Create use cases** - UC-001, UC-002, ... in order of importance
+3. **Define FRs** - FR-001, FR-002, ... linked to BRs
+4. **Build permission matrix** - Actor × Resource × Operation
+5. **Design UI structure** - 5 mandatory SeedData tables, navigation hierarchy
+6. **Sketch wireframes** - Key screens (List, Create, Detail)
+7. **Write Gherkin** - BDD scenarios for each UC
+8. **Define validations** - Field rules and business messages
+9. **Model lifecycle** - State machines, cross-module sync
+10. **Document dependencies** - External modules, cascading operations
+
+### 11.3 Data Model Validation
+
+Ensure:
+- No duplicate entity definitions
+- All FK relationships defined
+- All required fields marked
+- Enum values match business rules
+
+---
+
+## 12. Output & Status Update
+
+### 12.1 Write Specification Section
+
+Use `ba-writer.updateSpecification()` to write:
+
+```json
+{
+  "specification": {
+    "actors": [...],
+    "useCases": [...],
+    "functionalRequirements": [...],
+    "permissionMatrix": [...],
+    "entities": [...],
+    "navigationHierarchy": [...],
+    "wireframes": [...],
+    "gherkinScenarios": [...],
+    "validations": [...],
+    "messages": [...],
+    "lifeCycles": [...],
+    "crossModuleDependencies": [...],
+    "auditingPolicy": {...},
+    "archivalPolicy": {...}
+  }
+}
+```
+
+### 12.2 Update Status
+
+Use `ba-writer.updateStatus("specified")` to mark specification complete.
+
+### 12.3 User Confirmation
+
+Summarize for user:
+
+```
+✓ Specification complete
+
+Actors defined:     4 (Admin, Manager, User, Guest)
+Use cases created:  8 (UC-001 → UC-008)
+Requirements:       12 FRs linked to business rules
+Permission matrix:  3 resources × 4 actors
+SeedData tables:    5 mandatory (Status, Priority, Category, Type, Department)
+UI screens:         6 wireframes (List, Create, Detail, Reports, etc.)
+Gherkin scenarios:  18 scenarios across all UCs
+Validations:        24 field validation rules
+Entity lifecycle:   3 entities with state machines
+
+Next step: Validation (step-03-validate.md)
+```
+
+---
+
+## OUTPUT
+
+This step enriches **feature.json** with:
+- **specification** section containing actors, use cases, functional requirements, permission matrix, entities, navigation hierarchy, wireframes, Gherkin scenarios, validations, and data lifecycle
+- **Status:** "specified"
+
+**Delta mode:** Only affected UCs/FRs/permissions modified; existing ones preserved.
+**Micro mode:** Minimal specification with 1-2 UCs, 4-role permissions, basic CRUD FRs, essential SeedData only.