@atlashub/smartstack-cli 4.80.0 → 5.0.0

package/templates/skills/business-analyse/references/robustness-checks.md

@@ -1,426 +0,0 @@
-# Robustness Checks for Business Analysis
-
-> **Authoritative minimums:** See `_shared.md` § "Minimum Counts" for the single source of truth on all minimum thresholds.
-> **Objective:** Prevent incomplete specifications and broken references from reaching development.
-
-## Overview
-
-This document consolidates all robustness checks implemented across the business-analyse workflow. Each check serves to catch issues early, before they cause business-analyse-develop failures or runtime errors.
-
----
-
-## Phase 1: Module Specification Checklist (Step-03)
-
-> **When:** At end of step-03, before marking module status = "specified"
-> **Blocking:** YES - Module CANNOT proceed to consolidation with failing checks
-
-### Purpose
-
-Ensures each module has ALL required components before being marked as "specified". Prevents incomplete modules from reaching step-04 consolidation.
-
-### Checks (31 total)
-
-#### SECTION 1: Data Model (3 checks)
-
-| # | Check | Minimum | Blocking | Rationale |
-|---|-------|---------|----------|-----------|
-| 1.1 | Entities count | ≥2 | YES | Single-entity modules are rare and likely incomplete |
-| 1.2 | Entity attributes | Each entity ≥3 attributes | YES | Entities with <3 attributes are incomplete |
-| 1.3 | Entity relationships | All entities have relationships or marked standalone | NO (WARNING) | Standalone entities should be rare |
-
-#### SECTION 2: Business Rules (3 checks)
-
-| # | Check | Minimum | Blocking | Rationale |
-|---|-------|---------|----------|-----------|
-| 2.1 | Business rules count | ≥4 | YES | Modules need validation/calculation logic |
-| 2.2 | BR categories | ≥2 categories (VAL/CALC/WF/SEC/DATA) | YES | Single-category modules likely incomplete |
-| 2.3 | BR module prefixes | All BRs use module prefix | YES | Prevents ID collisions in multi-module apps |
-
-#### SECTION 3: Use Cases & Requirements (4 checks)
-
-| # | Check | Minimum | Blocking | Rationale |
-|---|-------|---------|----------|-----------|
-| 3.1 | Use cases count | ≥6 | YES | CRUD (5) + 1 business-specific minimum |
-| 3.2 | UC module prefixes | All UCs use module prefix | YES | Prevents ID collisions |
-| 3.3 | Functional requirements count | ≥4 | YES | FRs must cover key functionality |
-| 3.4 | UC-FR linkage | Every UC has ≥1 linked FR | NO (WARNING) | Orphan UCs indicate incomplete requirements |
-| 3.5 | FR-BR linkage | Every FR has ≥1 linked BR | NO (WARNING) | FRs without BRs may lack validation logic |
-
-#### SECTION 4: Permissions (3 checks)
-
-| # | Check | Minimum | Blocking | Rationale |
-|---|-------|---------|----------|-----------|
-| 4.1 | Permissions count | ≥5 | YES | CRUD (4) + 1 business action minimum |
-| 4.2 | Permission format | Module: `{app}.{module}.{action}` or Section: `{app}.{module}.{section}.{action}` | YES | Wrong format breaks RBAC system |
-| 4.3 | Role permissions | All roles have ≥1 permission | YES | Roles without permissions are useless |
-
-#### SECTION 5: UI & Navigation (4 checks)
-
-| # | Check | Minimum | Blocking | Rationale |
-|---|-------|---------|----------|-----------|
-| 5.1 | Sections count | ≥2 | YES | Modules need list + form minimum |
-| 5.2 | Wireframes count | 1 per section | YES | EVERY section MUST have wireframe |
-| 5.3 | Navigation entries | ≥1 | YES | Module must be accessible in menu |
-| 5.4 | Navigation route patterns | No `/detail/:id` suffix | YES | ALL sections use uniform route: module route + /{section-code}. list route MUST end with `/list`. FORBIDDEN: `/module/detail/:id` (detail is implicit) |
-
-#### SECTION 6: I18N & Messages (3 checks)
-
-| # | Check | Minimum | Blocking | Rationale |
-|---|-------|---------|----------|-----------|
-| 6.1 | i18n keys count | ≥42 | YES | Entities, fields, messages, validation, navigation |
-| 6.2 | i18n languages | All keys have 4 languages (fr/en/it/de) | YES | Missing translations break multi-language |
-| 6.3 | Messages count | ≥4 | YES | 1 success, 1 error, 1 warning, 1 info minimum |
-
-#### SECTION 7: Seed Data (2 checks)
-
-| # | Check | Minimum | Blocking | Rationale |
-|---|-------|---------|----------|-----------|
-| 7.1 | CORE seed data arrays | All 9 arrays present (per `_shared.md` § "Minimum Counts") | YES | Missing CORE data breaks deployment |
-| 7.2 | Business seed data | Template defined | NO (WARNING) | Helps with testing |
-
-**CORE arrays required (9 total — see `_shared.md` § "seedDataCore arrays"):**
-1. `navigationApplications` — required once per application
-2. `applicationRoles` — required once per application
-3. `navigationModules` — one per module
-4. `navigationSections` — one per section (list, detail, create, etc.)
-5. `navigationResources` — optional per resource
-6. `navigationTranslations` — 4 languages per nav module
-7. `permissions` — CRUD + business actions per module
-8. `rolePermissions` — role to permission mappings
-9. `permissionConstants` — PascalCase constants for code
-
-#### SECTION 8: API Endpoints (2 checks)
-
-| # | Check | Minimum | Blocking | Rationale |
-|---|-------|---------|----------|-----------|
-| 8.1 | API endpoints count | ≥5 | YES | CRUD (5) minimum |
-| 8.2 | API permissions | Every endpoint has permission | YES | Endpoints without permissions are security holes |
-
-#### SECTION 9: Validations (1 check)
-
-| # | Check | Minimum | Blocking | Rationale |
-|---|-------|---------|----------|-----------|
-| 9.1 | Validations count | ≥1 | YES | Modules need field validation rules |
-
-#### SECTION 10: Gherkin Scenarios (1 check)
-
-| # | Check | Minimum | Blocking | Rationale |
-|---|-------|---------|----------|-----------|
-| 10.1 | Gherkin scenarios count | ≥2 | NO (WARNING) | Enables automated testing |
-
-### Failure Handling
-
-**IF ANY blocking check fails:**
-
-1. **STOP** - Do NOT mark module as "specified"
-2. **DISPLAY** table of failures with details
-3. **ACTIONS:**
-   - Fix ALL blocking failures
-   - Re-run step-03 module specification
-   - Proceed only when ALL blocking checks pass
-
-**Example output:**
-
-```
-═══════════════════════════════════════════════════════════════
-  MODULE SPECIFICATION INCOMPLETE - Projects
-═══════════════════════════════════════════════════════════════
-
-| Section | Check | Required | Actual | Status | Details |
-|---------|-------|----------|--------|--------|---------|
-| Business Rules | BR categories | ≥2 | 1 | ✗ FAIL | Only VAL category present |
-| Use Cases | UC count | ≥6 | 4 | ✗ FAIL | Missing business-specific UCs |
-| Wireframes | Count | 3 | 2 | ✗ FAIL | Missing wireframe for "Settings" section |
-
-ACTIONS REQUIRED:
-1. Add business rules in ≥1 other category (CALC, WF, SEC, or DATA)
-2. Add 2 more use cases (business-specific)
-3. Create wireframe for "Settings" section
-4. Re-run step-03 validation
-
-DO NOT PROCEED TO CONSOLIDATION UNTIL ALL CHECKS PASS
-═══════════════════════════════════════════════════════════════
-```
-
----
-
-## Phase 2: Cross-Module Reference Validation (Step-04)
-
-> **When:** During consolidation, before marking application as "consolidated"
-> **Blocking:** YES - Unresolved references BLOCK handoff
-
-### Purpose
-
-Verifies ALL cross-module entity references are resolvable. Prevents FK constraint violations and runtime errors during business-analyse-develop code generation.
-
-### Process
-
-1. **Build Entity Registry**
-   - Extract all entities from all modules
-   - Map: `{moduleCode → [entities]}`
-
-2. **Extract Cross-Module References**
-   - Scan all `entity.relationships[]` for references to other modules
-   - Format: `"ModuleName.EntityName.FieldName"` or `"ModuleName.EntityName"`
-
-3. **Validate References**
-   - ✓ Target module exists
-   - ✓ Target entity exists in target module
-   - ✓ Target field exists (if specified)
-
-4. **Validate Dependency Graph Alignment**
-   - For each cross-module reference, verify dependency edge exists
-   - Auto-fix: add missing edges (with warning)
-
-5. **Detect Circular Dependencies**
-   - BLOCKING ERROR if cycles detected
-   - User must break cycles manually
-
-### Checks
-
-| # | Check | Blocking | Failure Action |
-|---|-------|----------|----------------|
-| 1 | Target module exists | YES | BLOCKING ERROR - list invalid references |
-| 2 | Target entity exists | YES | BLOCKING ERROR - list invalid references |
-| 3 | Target field exists | NO (WARNING) | Assume PK ("Id") if not specified |
-| 4 | Dependency edge exists | NO (WARNING) | Auto-fix: add missing edge |
-| 5 | No circular dependencies | YES | BLOCKING ERROR - user must fix |
-
-### Example Output
-
-**Success:**
-
-```
-═══════════════════════════════════════════════════════════════
-  CROSS-MODULE REFERENCES VALIDATED
-═══════════════════════════════════════════════════════════════
-
-| Source Module | Source Entity | Target | Type | Status |
-|---------------|---------------|--------|------|--------|
-| TimeTracking | TimeEntry | Projects.Project.Id | FK (N:1) | ✓ RESOLVED |
-| LeaveManagement | LeaveRequest | Projects.Employee.Id | FK (N:1) | ✓ RESOLVED |
-| AbsenceManagement | Absence | Projects.Employee.Id | FK (N:1) | ✓ RESOLVED |
-| Reporting | ProjectReport | Projects.Project.Id | FK (N:1) | ✓ RESOLVED |
-
-Total: 4 cross-module references
-All references RESOLVED ✓
-No circular dependencies ✓
-═══════════════════════════════════════════════════════════════
-```
-
-**Failure (unresolved reference):**
-
-```
-═══════════════════════════════════════════════════════════════
-  CROSS-MODULE REFERENCES FAILED
-═══════════════════════════════════════════════════════════════
-
-BLOCKING ERRORS:
-
-1. Module "TimeTracking": Entity "TimeEntry" references non-existent entity "Task" in module "Projects"
-   - Source: TimeEntry.taskId
-   - Target: Projects.Task (NOT FOUND)
-   - Fix: Either create "Task" entity in Projects module, or remove reference
-
-2. Module "Reporting": Entity "ProjectReport" references non-existent module "Analytics"
-   - Source: ProjectReport.analyticsId
-   - Target: Analytics.Report (module does not exist)
-   - Fix: Either create "Analytics" module, or remove reference
-
-ACTIONS REQUIRED:
-1. Fix ALL unresolved references listed above
-2. Return to step-03 for affected modules
-3. Re-run step-04 consolidation
-
-DO NOT PROCEED TO HANDOFF UNTIL ALL REFERENCES RESOLVED
-═══════════════════════════════════════════════════════════════
-```
-
-**Failure (circular dependency):**
-
-```
-═══════════════════════════════════════════════════════════════
-  CIRCULAR DEPENDENCIES DETECTED
-═══════════════════════════════════════════════════════════════
-
-BLOCKING ERROR: Cycles found in dependency graph
-
-Cycle 1: Orders → Invoices → Payments → Orders
-Cycle 2: Customers → Contacts → Customers
-
-ACTIONS REQUIRED:
-1. Break cycles by:
-   - Moving shared entities to a separate "Core" module
-   - Using event-driven communication instead of FK
-   - Removing unnecessary dependencies
-2. Return to step-02 decomposition
-3. Fix dependency graph
-4. Re-run step-03 module specification
-5. Re-run step-04 consolidation
-
-DEVELOPMENT CANNOT PROCEED WITH CIRCULAR DEPENDENCIES
-═══════════════════════════════════════════════════════════════
-```
-
----
-
-> **Note:** Ralph Readiness Validation (PRD files, handoff completeness, etc.) is handled by the `/business-analyse-handoff` skill.
-
----
-
-## Common Patterns & Best Practices
-
-### 1. Fail Fast, Fail Clear
-
-**Principle:** Detect issues as early as possible, provide clear error messages with actionable fixes.
-
-**Example:**
-- ✗ BAD: "Validation failed" (vague, no action)
-- ✓ GOOD: "Entity 'Task' not found in Projects module. Fix: Create Task entity or remove reference from TimeEntry.taskId"
-
-### 2. Progressive Validation
-
-**Principle:** Validate at each step, not just at the end.
-
-**Checkpoints:**
-- Step-03d: Module completeness (before marking "specified")
-- Step-04: Cross-module coherence (before marking "consolidated")
-
-### 3. Auto-Fix vs. Manual Fix
-
-**Auto-fix (safe):**
-- Add missing dependency edges (with warning)
-- Auto-correct casing (PascalCase, camelCase)
-- Fill default values (e.g., PK = "Id" if not specified)
-
-**Manual fix (requires user decision):**
-- Circular dependencies (how to break?)
-- Unresolved entity references (create or remove?)
-- Permission conflicts (intentional or error?)
-
-### 4. Severity Levels
-
-| Level | Symbol | Meaning | Action |
-|-------|--------|---------|--------|
-| PASS | ✓ | Check passed | Continue |
-| WARNING | ⚠ | Non-blocking issue | Recommend fix, allow continue |
-| ERROR | ✗ | Blocking issue | STOP, fix required |
-
-### 5. Display Standards
-
-**Always include in error messages:**
-1. **What failed** - Clear identification of the issue
-2. **Why it matters** - Impact if not fixed
-3. **How to fix** - Specific actionable steps
-4. **Where to go** - Which step to return to
-
-**Example:**
-
-```
-✗ BLOCKING ERROR: Cross-module reference unresolved
-
-WHAT: TimeTracking.TimeEntry references Projects.Task (NOT FOUND)
-WHY: This will cause FK constraint violation in database
-HOW TO FIX:
-  Option 1: Create "Task" entity in Projects module
-  Option 2: Remove reference from TimeEntry (change taskId to projectId)
-WHERE: Return to step-03-specify.md for TimeTracking module
-```
-
----
-
-## Troubleshooting Guide
-
-### Issue: Module Fails Specification Checklist
-
-**Symptoms:**
-- Module has < minimum required components
-- Step-03d validation fails
-
-**Diagnosis:**
-1. Check which sections failed (entities, UCs, BRs, wireframes, etc.)
-2. Review minimum requirements per section
-
-**Fix:**
-1. Add missing components until minimums met
-2. Re-run step-03 validation
-3. Proceed only when ALL blocking checks pass
-
----
-
-### Issue: Cross-Module Reference Unresolved
-
-**Symptoms:**
-- Step-04 reports "entity not found"
-- Cross-module FK references fail validation
-
-**Diagnosis:**
-1. Identify source module + entity
-2. Identify target module + entity
-3. Check if target entity exists in target module
-
-**Fix:**
-1. **If target entity missing:**
-   - Create target entity in target module
-   - OR remove reference from source entity
-2. **If target module missing:**
-   - Create target module
-   - OR remove reference from source entity
-3. Re-run step-04 consolidation
-
----
-
-### Issue: Circular Dependencies Detected
-
-**Symptoms:**
-- Step-04 reports "circular dependencies"
-- Dependency graph has cycles
-
-**Diagnosis:**
-1. Identify cycle path (A → B → C → A)
-2. Analyze relationships causing cycle
-
-**Fix:**
-1. **Option 1: Create Core module**
-   - Move shared entities to new "Core" module
-   - Other modules depend on Core (no cycle)
-2. **Option 2: Use events instead of FK**
-   - Replace direct FK with event-driven communication
-   - Breaks dependency link
-3. **Option 3: Remove unnecessary dependency**
-   - Review if dependency is truly needed
-   - Remove if redundant
-4. Return to step-02-structure, fix dependency graph
-5. Re-run step-03-specify for affected modules
-6. Re-run step-04-consolidate
-
----
-
-## Metrics & Success Criteria
-
-### Module Specification Checklist
-
-**Target:**
-- 100% blocking checks passed
-- 0-5 warnings acceptable
-
-**Success:**
-- Module marked as "specified"
-- Ready for consolidation
-
-### Cross-Module Validation
-
-**Target:**
-- 100% references resolved
-- 0 circular dependencies
-
-**Success:**
-- Application marked as "consolidated"
-- Ready for `/business-analyse-html` and `/business-analyse-handoff`
-
----
-
-**Last Updated:** 2026-02-08
-**Version:** 1.0
-**Author:** SmartStack CLI Team
-**Based on:** Analysis of BA session 03b76b8b-ea1c-4f1e-a636-bd46b0c33e02

package/templates/skills/business-analyse/references/ui-dashboard-spec.md

@@ -1,85 +0,0 @@
-# UI: Dashboard Specification
-
-> Reference for step-03-specify.md — section 3d dashboard KPI and chart capture.
-
-## 3d. Dashboard Specification (if section = dashboard)
-
-When a "dashboard" section is selected, capture structured KPI and chart data **in addition** to the standard ASCII mockup.
-
-1. **Ask client for KPIs** via AskUserQuestion (batch):
-   - KPI name and metric description
-   - Visualization type: `kpi-card`, `bar`, `line`, `pie`, `area`, `donut`, `stacked-bar`
-   - Data source entity
-   - Format: `number`, `currency`, `percent`, `duration`
-   - Thresholds (warning/critical) if applicable
-
-2. **Ask client for filters:**
-   - Date range filter? Default period? (day/week/month/quarter/year)
-   - Entity-based filters? (status, category, etc.)
-
-3. **Ask client for refresh mode:**
-   - Static (load on page open)
-   - Polling (periodic refresh)
-   - SignalR (real-time push)
-
-4. **Store in specification.dashboards[]:**
-
-```json
-{
-  "code": "{module}-dashboard",
-  "title": "{Module} Dashboard",
-  "description": "Vue d'ensemble des métriques {module}",
-  "linkedUCs": ["UC-XXX"],
-  "refreshMode": "static",
-  "defaultPeriod": "month",
-  "kpis": [
-    {
-      "code": "total-items",
-      "label": "Total Items",
-      "metric": "COUNT(entity)",
-      "format": "number",
-      "visualization": "kpi-card",
-      "dataSource": "Entity",
-      "thresholds": { "warning": 100, "critical": 50 }
-    },
-    {
-      "code": "items-by-status",
-      "label": "Items by Status",
-      "metric": "COUNT(entity) GROUP BY status",
-      "format": "number",
-      "visualization": "pie",
-      "dataSource": "Entity",
-      "dimensions": ["status"]
-    }
-  ],
-  "filters": [
-    { "field": "dateRange", "type": "dateRange", "label": "Période" },
-    { "field": "status", "type": "multiselect", "label": "Statut" }
-  ],
-  "permissionsRequired": ["{app}.{module}.read"]
-}
-```
-
-5. **ALSO generate the standard ASCII mockup** for the dashboard with KPI cards + chart placeholders:
-
-```
-╔═══════════════════════════════════════════════════════════════╗
-║  {Module} > Dashboard              Période: [Ce mois ▾]     ║
-╠═══════════════════════════════════════════════════════════════╣
-║  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐    ║
-║  │ KPI #1   │  │ KPI #2   │  │ KPI #3   │  │ KPI #4   │    ║
-║  │  1,234   │  │  567     │  │  89.2%   │  │  12,400  │    ║
-║  │  ↑ +12%  │  │  ↓ -3%  │  │  → 0%   │  │  ↑ +5%   │    ║
-║  └──────────┘  └──────────┘  └──────────┘  └──────────┘    ║
-╠═══════════════════════════════════════════════════════════════╣
-║  ┌─────────────────────────┐  ┌─────────────────────────┐    ║
-║  │  [Bar Chart]            │  │  [Pie Chart]            │    ║
-║  │  Items by Month         │  │  Items by Status        │    ║
-║  │  ████                   │  │      ████████           │    ║
-║  │  ████ ████              │  │   ███      ███          │    ║
-║  │  ████ ████ ████         │  │  ██   42%    ██         │    ║
-║  └─────────────────────────┘  └─────────────────────────┘    ║
-╚═══════════════════════════════════════════════════════════════╝
-```
-
-Store the mockup in specification.wireframes[] AS WELL (for visual reference).