@atlashub/smartstack-cli 2.1.0 → 2.2.0

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

@@ -1,472 +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` |
-
----
-
-### 6b. Specify Navigation Hierarchy & SeedData Requirements
-
-> **CRITICAL:** Every new feature requires navigation entries and seed data to be functional.
-> Without these, the module will be invisible and permissions will block all access (403).
-
-**Navigation hierarchy for this feature:**
-
-```markdown
-### Navigation Hierarchy
-
-| Level | Code | Label (EN) | Label (FR) | Route | Icon | New? |
-|-------|------|-----------|-----------|-------|------|------|
-| Context | business | Business | Métier | /business | Briefcase | Existing/New |
-| Application | {application_name} | {App Label EN} | {App Label FR} | /business/{app} | {Icon} | Existing/New |
-| Module | {module_name} | {Module Label EN} | {Module Label FR} | /business/{app}/{module} | {Icon} | **NEW** |
-| Section (opt.) | {section} | {Section Label EN} | {Section Label FR} | /business/{app}/{module}/{section} | {Icon} | **NEW** |
-```
-
-> **Rule:** Only create entries marked "New". Existing entries are reused from the database.
-> Provide labels in 4 languages: FR, EN, IT, DE.
-
-**Permission hierarchy for this module:**
-
-```markdown
-### Permission Hierarchy (HasData seeds)
-
-| Permission Path | Level | Action | Description |
-|----------------|-------|--------|-------------|
-| `business.{app}.{module}.*` | Module | Wildcard | Full module access |
-| `business.{app}.{module}.read` | Module | Read | View list and details |
-| `business.{app}.{module}.create` | Module | Create | Create new entries |
-| `business.{app}.{module}.update` | Module | Update | Modify existing |
-| `business.{app}.{module}.delete` | Module | Delete | Remove entries |
-| `business.{app}.{module}.export` | Module | Execute | Export data (if needed) |
-```
-
-**Role-Permission assignments (default matrix):**
-
-| Permission | {App} Admin | {App} Manager | {App} Contributor | {App} Viewer |
-|------------|-------------|---------------|-------------------|--------------|
-| `*.{module}.*` | X | - | - | - |
-| `*.{module}.read` | - | X | X | X |
-| `*.{module}.create` | - | X | X | - |
-| `*.{module}.update` | - | X | X | - |
-| `*.{module}.delete` | - | - | - | - |
-| `*.{module}.export` | - | X | - | - |
-
-> **Note:** Admin gets wildcard (includes all actions). SuperAdmin inherits via `*` wildcard.
-
-**SeedData files to create/modify:**
-
-> **5 mandatory files** for every new module (4 EF Core HasData + 1 Application code):
-
-| # | File | Layer | Action | Content |
-|---|------|-------|--------|---------|
-| 1 | `NavigationModuleConfiguration.cs` | Infrastructure (HasData) | Add entry | Module in `nav_Modules` |
-| 2 | `NavigationTranslationConfiguration.cs` | Infrastructure (HasData) | Add entries | 4 translations (fr, en, it, de) per nav entity |
-| 3 | `PermissionConfiguration.cs` | Infrastructure (HasData) | Add entries | All permissions listed above |
-| 4 | `Permissions.cs` | Application (code) | Add static class | Compile-time constants for `[RequirePermission]` |
-| 5 | `RolePermissionConfiguration.cs` | Infrastructure (HasData) | Add entries | Role→Permission for {App} Admin, {App} Manager, {App} Contributor, {App} Viewer |
-
----
-
-### 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`