@atlashub/smartstack-cli 1.34.0 → 1.35.0

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

@@ -1,25 +1,21 @@
 ---
 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>
+## YOUR TASK:
+
 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>
+> **ULTRATHINK MODE:**
+> - Extract IMPLICIT rules from discovery responses
+> - Challenge completeness of each rule
+> - Verify no rule contradicts another
+> - Ensure rules are testable
 
-## EXECUTION SEQUENCE
+## EXECUTION SEQUENCE:
 
 ### 1. Read Current State
 
@@ -28,12 +24,16 @@ 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/frd-brd.md    # ~90 lines only (vs 477 lines full 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.
@@ -141,6 +141,10 @@ Identify:
 - 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
 
 ---
 
@@ -159,7 +163,7 @@ For each integration, note:
 
 ### 9. Compile BRD Document
 
-Assemble using `templates/frd-brd.md` structure:
+Assemble using `templates/tpl-brd.md` structure:
 
 ```markdown
 # BRD - {feature_id} {feature_description}
@@ -200,6 +204,40 @@ Assemble using `templates/frd-brd.md` structure:
 
 ---
 
+### 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`
@@ -213,16 +251,18 @@ Update `00-context.md`:
 ### 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)
-```
+
+| 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?"
@@ -234,10 +274,26 @@ Read and execute: steps/step-03-specify.md
 
 ---
 
-## OUTPUT
+## 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,29 +1,25 @@
 ---
 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>
+## YOUR TASK:
+
 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>
+> **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
+## EXECUTION SEQUENCE:
 
 ### 1. Read Current State
 
@@ -32,12 +28,16 @@ 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/frd-spec.md    # ~150 lines (UC + FR + permissions sections)
+Read: templates/tpl-frd.md    # ~150 lines (UC + FR + permissions sections)
 ```
 
 This template contains ONLY the FRD structure.
@@ -271,12 +271,86 @@ Feature: {feature_id} {feature_description}
 
 ---
 
+### 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`
@@ -290,16 +364,18 @@ Update `00-context.md`:
 ### 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)
-```
+
+| 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:**
 ```
@@ -308,10 +384,26 @@ Read and execute: steps/step-04-validate.md
 
 ---
 
-## OUTPUT
+## 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`

package/templates/skills/business-analyse/steps/step-04-validate.md

@@ -1,17 +1,15 @@
 ---
 name: step-04-validate
 description: Validation gate - APPROVED or REJECTED decision
-model: haiku
-prev_step: steps/step-03-specify.md
 next_step: steps/step-05-handoff.md
 ---
 
-<objective>
+## YOUR TASK:
+
 Validate that all specifications are complete and consistent.
 Gate decision: APPROVED or REJECTED with reasons.
-</objective>
 
-## EXECUTION SEQUENCE
+## EXECUTION SEQUENCE:
 
 ### 1. Read Current State
 
@@ -23,6 +21,10 @@ Read all previous outputs:
 
 Update progress: `04-validate` -> "In Progress"
 
+**Read digest from previous step:**
+Read `{output_dir}/digest-03.md` for compressed context from previous step.
+**DO NOT read full output files** unless in resume mode (`-r`).
+
 ---
 
 ### 2. Completeness Checklist
@@ -88,7 +90,28 @@ INVALID: {app}.{module}.{action}
 
 ---
 
-### 5. Risk Assessment
+### 5. Documentation Freshness Check
+
+**If `docs-manifest.json` exists in project root:**
+
+| Check | Expected | Status |
+|-------|----------|--------|
+| Module has manifest entry | Entry exists | {OK/MISSING} |
+| Last doc update < 30 days from last code change | Within threshold | {OK/DRIFT} |
+| All 8 business-first sections present | 8/8 | {X/8} |
+| i18n FR complete (minimum) | All keys present | {OK/INCOMPLETE} |
+| frd-data.ts exists | File present | {OK/MISSING} |
+
+**If drift detected:**
+- Add to validation report: `"documentationDrift": true`
+- Add to issues: `"Documentation is {N} days behind code changes"`
+- Severity: WARNING (non-blocking for BA validation)
+
+**If `docs-manifest.json` absent:** Skip this section silently.
+
+---
+
+### 6. Risk Assessment
 
 | Risk | Severity | Mitigation |
 |------|----------|------------|
@@ -102,7 +125,7 @@ INVALID: {app}.{module}.{action}
 
 ---
 
-### 6. Make Decision
+### 7. Make Decision
 
 **APPROVED if:**
 - All completeness checks pass (100%)
@@ -118,7 +141,42 @@ INVALID: {app}.{module}.{action}
 
 ---
 
-### 7. Generate Validation Report
+### 8b. Generate Context Digest
+
+**Write digest to:** `{output_dir}/digest-04.md`
+
+```markdown
+# Digest: Step 04 - Validate
+
+## Changes
+- {output_dir}/validation.json: Validation report created
+
+## Decisions
+- Gate decision: {APPROVED/REJECTED}
+- Completeness: {score}
+- Consistency: {all checks status}
+
+## Findings
+- Convention compliance: {status}
+- Documentation drift: {status}
+- Risks: {count} identified, {count} mitigated
+
+## State Updates
+| Variable | New Value |
+|----------|-----------|
+| validation_status | {APPROVED/REJECTED} |
+| completeness_score | {score} |
+| risk_count | {count} |
+
+## For Next Step
+- Validation: {APPROVED/REJECTED}
+- If REJECTED: {list of issues to fix}
+- If APPROVED: ready for handoff generation
+```
+
+---
+
+### 9. Generate Validation Report
 
 ```json
 {
@@ -166,7 +224,7 @@ INVALID: {app}.{module}.{action}
 
 ---
 
-### 8. Save Output
+### 10. Save Output
 
 Write to: `{output_dir}/validation.json`
 
@@ -176,39 +234,39 @@ Update `00-context.md`:
 
 ---
 
-### 9. Handle Decision
+### 11. Handle Decision
 
 **If APPROVED:**
 
 Display:
-```
-VALIDATION - {feature_id}
-├── Status: APPROVED
-├── Completeness: 100%
-├── Consistency: All checks passed
-├── Conventions: SmartStack compliant
-├── Risks: {count} mitigated
-├── Output: {output_dir}/validation.json
-└── Next: step-05-handoff (Development prompt)
-```
+
+| Field | Value |
+|-------|-------|
+| Step | VALIDATION |
+| Feature | {feature_id} |
+| Status | APPROVED |
+| Completeness | 100% |
+| Consistency | All checks passed |
+| Conventions | SmartStack compliant |
+| Risks | {count} mitigated |
+| Output | {output_dir}/validation.json |
+| Next | step-05-handoff (Development prompt) |
 
 Load next step: `steps/step-05-handoff.md`
 
 **If REJECTED:**
 
 Display:
-```
-VALIDATION - {feature_id}
-├── Status: REJECTED
-├── Issues found:
-│   ├── {issue 1}
-│   ├── {issue 2}
-│   └── {issue 3}
-├── Required actions:
-│   ├── {action 1}
-│   └── {action 2}
-└── Next: Revise specifications
-```
+
+| Field | Value |
+|-------|-------|
+| Step | VALIDATION |
+| Feature | {feature_id} |
+| Status | REJECTED |
+| Issues | {issue 1}, {issue 2}, {issue 3} |
+| Action 1 | {action 1} |
+| Action 2 | {action 2} |
+| Next | Revise specifications |
 
 **Ask user:**
 ```json
@@ -230,10 +288,26 @@ VALIDATION - {feature_id}
 
 ---
 
-## OUTPUT
+## OUTPUT FORMAT:
 
 This step produces:
 - `{output_dir}/validation.json` (created)
 - `{output_dir}/00-context.md` (updated)
 
 Gate decision enables or blocks next step.
+
+## ERROR HANDLING:
+
+**If previous output files are missing:**
+1. List which files exist vs expected
+2. If partial: validate only available documents
+3. Add "Missing document" as CRITICAL issue in validation report
+
+**If validation gate REJECTED:**
+1. Present issues to user with severity
+2. Offer: auto-revise / manual revision / force approval
+3. If auto-revise: loop back to the step that needs fixing
+
+## NEXT STEP:
+
+After completion, proceed to `steps/step-05-handoff.md`