project-iris 0.0.16 → 0.0.18

package/flows/aidlc/skills/inception/review.md

@@ -14,14 +14,16 @@
 ## Success Metrics
 
 - ✅ All artifacts verified with ✅ or 🚫 status
+- ✅ Traceability chain validated (Intent→Requirements→Units→Stories→Bolts)
 - ✅ Gaps clearly identified with recommended actions
-- ✅ Final summary shows counts (requirements, units, stories, bolts)
+- ✅ Final summary shows counts (requirements, risks, units, stories, bolts)
 - ✅ Clear transition to Construction Agent
 
 ## Failure Modes
 
 - ❌ Using ASCII table for checkpoints
 - ❌ Not verifying all artifact types
+- ❌ Skipping traceability validation
 - ❌ Skipping gap identification
 - ❌ Not updating inception-log.md on completion
 
@@ -35,6 +37,7 @@ Show at start of this skill:
 ### Inception Progress
 - [x] Intent created
 - [x] Requirements gathered
+- [x] Risks defined
 - [ ] Artifacts reviewed  ← current
 - [ ] Ready for Construction
 ```
@@ -70,14 +73,57 @@ Ensure all inception artifacts are complete, consistent, and ready for Construct
 
 Check existence and completeness of all required artifacts:
 
-- **Requirements**: `{intent}/requirements.md` - FR, NFR, constraints
+- **Requirements**: `{intent}/requirements.md` - FR, NFR, SLOs, constraints
+- **Risks**: `{intent}/risks.md` - Risk register with mitigations
 - **System Context**: `{intent}/system-context.md` - Actors, external systems, data flows
 - **Units**: `{intent}/units.md` - Unit list with purposes
 - **Unit Briefs**: `{intent}/units/{unit}/unit-brief.md` - Scope, entities, success criteria
 - **Stories**: `{intent}/units/{unit}/stories/*.md` - Acceptance criteria
 - **Bolts**: Path from `schema.bolts` - Type, stories, status
 
-### 2. Consistency Check
+### 2. Traceability Validation (CRITICAL)
+
+Verify complete artifact traceability chain:
+
+```text
+Intent → Requirements → Units → Stories → Bolts
+             ↓
+          Risks (linked to requirements)
+```
+
+**Traceability Matrix Checks:**
+
+1. **Intent → Requirements**
+   - [ ] All FRs trace to business intent (from intent.md goal)
+   - [ ] All NFRs have measurable SLOs defined
+   - [ ] Trade-offs documented when requirements conflict
+
+2. **Requirements → Units**
+   - [ ] Every FR is assigned to exactly one unit
+   - [ ] No orphan FRs (requirements without units)
+   - [ ] FR-to-unit mapping documented in units.md
+
+3. **Requirements → Risks**
+   - [ ] High-impact FRs/NFRs have associated risks
+   - [ ] Each risk links to Related Requirements (FR-N, NFR-X)
+   - [ ] Critical risks have mitigation strategies
+
+4. **Units → Stories**
+   - [ ] Each unit has stories derived from its assigned FRs
+   - [ ] No orphan stories (stories without unit)
+   - [ ] Story count matches expected based on FR complexity
+
+5. **Stories → Bolts**
+   - [ ] Every story is assigned to exactly one bolt
+   - [ ] No orphan stories (stories without bolts)
+   - [ ] Bolt dependencies respect story dependencies
+
+**Validation Outcome:**
+- ✅ = Complete traceability
+- ⚠️ = Partial traceability (gaps identified)
+- ❌ = Broken traceability (must fix before Construction)
+
+### 3. Consistency Check
 
 Verify cross-artifact consistency:
 
@@ -93,18 +139,29 @@ Verify cross-artifact consistency:
 ```text
 ### Artifacts Review
 
+**Traceability Status**
+- ✅ Intent → Requirements: {n} FRs, {m} NFRs
+- ✅ Requirements → Units: All FRs mapped
+- ✅ Requirements → Risks: {r} risks linked
+- ✅ Units → Stories: {s} stories from {u} units
+- ✅ Stories → Bolts: All stories assigned
+
+**Risks** ({n} identified)
+- Critical: {count} | High: {count} | Medium: {count} | Low: {count}
+- Key risks: {top 3 critical/high risks}
+
 **System Context**
 - Actors: {list}
 - External systems: {list}
 - Data flows: {summary}
 
 **Units**
-- {unit-1}: {purpose}
-- {unit-2}: {purpose}
+- {unit-1}: {purpose} - FRs: FR-1, FR-2
+- {unit-2}: {purpose} - FRs: FR-3, FR-4
 
 **Stories** ({n} total)
-- {unit-1}: S1, S2, S3
-- {unit-2}: S4, S5
+- {unit-1}: S1, S2, S3 → FR-1, FR-2
+- {unit-2}: S4, S5 → FR-3, FR-4
 
 **Bolt Plan** ({n} bolts)
 - bolt-{unit-1}-1: Stories S1-S3
@@ -161,6 +218,8 @@ status: complete
 
 - **Functional Requirements**: {n}
 - **Non-Functional Requirements**: {n}
+- **SLOs Defined**: {n}
+- **Risks Identified**: {n} (Critical: {n}, High: {n})
 - **Units**: {n}
 - **Stories**: {n}
 - **Bolts Planned**: {n}
@@ -168,7 +227,8 @@ status: complete
 ## Ready for Construction
 
 **Checklist**:
-- [x] All requirements documented
+- [x] All requirements documented (FR, NFR, SLOs)
+- [x] Risks identified and mitigated
 - [x] System context defined
 - [x] Units decomposed
 - [x] Stories created for all units
@@ -204,6 +264,8 @@ status: inception-complete
 Summary:
 - {n} functional requirements
 - {m} non-functional requirements
+- {p} SLOs defined
+- {r} risks identified (Critical: {c}, High: {h})
 - {x} units
 - {y} stories
 - {z} bolts planned
@@ -225,8 +287,10 @@ Ready to start construction?
 
 ### Verification Results
 
-- ✅ Artifacts complete
-- ✅ Cross-references valid
+- ✅ Requirements complete (FR, NFR, SLOs)
+- ✅ Risks documented with mitigations
+- ✅ System context defined
+- ✅ Traceability chain complete
 - ✅ Stories have acceptance criteria
 - ✅ Bolts planned
 
@@ -265,7 +329,7 @@ If gaps found at Checkpoint 3:
 ## Test Contract
 
 ```yaml
-input: All inception artifacts (requirements, context, units, stories, bolts)
+input: All inception artifacts (requirements, risks, context, units, stories, bolts)
 output: inception-log.md updated, intent status = inception-complete
 checkpoints: 2
   - Checkpoint 3: Artifacts reviewed and approved

package/flows/aidlc/skills/inception/risks.md

@@ -0,0 +1,541 @@
+# Skill: Define Risk Register
+
+---
+
+## Mandatory Output Rules (READ FIRST)
+
+### General Rules
+- 🚫 **NEVER** use ASCII tables for options - they break at different terminal widths
+- ✅ **ALWAYS** use numbered list format: `N - **Option**: Description`
+- ✅ **ALWAYS** use status indicators: ✅ (done) ⏳ (current) [ ] (pending)
+- ✅ **ALWAYS** show progress tracker at start
+- ✅ **ALWAYS** ask clarifying questions BEFORE generating risks
+- ✅ **ALWAYS** present FULL risk register at review (no summaries)
+- 🛑 **STOP** at each checkpoint - wait for user response
+
+### Risk Register Rules
+- ✅ **ALWAYS** categorize risks (Technical, Business, Operational, External, Compliance)
+- ✅ **ALWAYS** use standard impact/likelihood scoring (1-5 scale)
+- ✅ **ALWAYS** calculate risk score (Impact × Likelihood)
+- ✅ **ALWAYS** define mitigation strategy for High/Critical risks
+- ✅ **ALWAYS** assign ownership for each mitigation
+- ✅ **ALWAYS** align with organization's Risk Register format if present
+
+## Success Metrics
+
+- ✅ Clarifying questions asked before generating risks
+- ✅ All 5 risk categories addressed (Technical, Business, Operational, External, Compliance)
+- ✅ Each risk has: Category, Description, Impact, Likelihood, Score, Mitigation, Owner
+- ✅ High/Critical risks (score ≥ 12) have detailed mitigation plans
+- ✅ Risks linked to relevant requirements (FR/NFR)
+- ✅ Org Risk Register alignment documented (if applicable)
+
+## Failure Modes
+
+- ❌ Generating risks without asking discovery questions first
+- ❌ Risks without impact/likelihood scoring
+- ❌ High-score risks without mitigation strategies
+- ❌ Skipping risk categories without explicit confirmation
+- ❌ Vague risks without specific triggers or consequences
+- ❌ Summarizing at review instead of showing full details
+
+---
+
+## Progress Display
+
+Show at start of this skill:
+
+```text
+### Inception Progress
+- [x] Intent created
+- [x] Requirements gathered
+- [ ] Risks defined  ← current
+- [ ] Artifacts reviewed (Context + Units + Stories + Bolts)
+- [ ] Ready for Construction
+```
+
+---
+
+## Checkpoints
+
+- **Checkpoint 1**: Risk discovery questions answered
+- **Checkpoint 2**: Full risk register review and approval
+
+---
+
+## Goal
+
+Identify, analyze, and document project risks with mitigation strategies, aligning with the organization's Risk Register format where applicable. This follows AI-DLC's requirement for "Description of Risks (matching with organization's Risk Register, if present)".
+
+---
+
+## Input
+
+- **Required**: Intent name or path
+- **Required**: `requirements.md` for the intent
+- **Required**: `.iris/aidlc/memory-bank.yaml` - artifact schema
+- **Optional**: Existing `risks.md` to update
+- **Optional**: Organization's Risk Register template
+
+**Note**: Risks should trace to specific requirements (FR/NFR) identified in the requirements phase.
+
+---
+
+## Process
+
+### Step 1: Risk Discovery
+
+**Checkpoint 1**: Ask clarifying questions BEFORE generating risks.
+
+```markdown
+## Risk Discovery
+
+Before I generate the risk register, I need to understand:
+
+### Technical Risks
+1. What are the most complex technical components?
+2. Any new/unfamiliar technologies being used?
+3. Integration points with external systems?
+4. Performance or scalability concerns from NFRs?
+
+### Business Risks
+5. What happens if the feature fails to deliver value?
+6. Competitive pressures or time-to-market concerns?
+7. User adoption risks?
+
+### Operational Risks
+8. Deployment complexity?
+9. Monitoring/observability gaps?
+10. On-call/support readiness?
+
+### External Risks
+11. Third-party dependencies (APIs, services)?
+12. Vendor lock-in concerns?
+13. Supply chain vulnerabilities?
+
+### Compliance Risks
+14. Regulatory requirements (from NFRs)?
+15. Data privacy concerns?
+16. Audit trail requirements?
+
+### Organizational Context
+17. Does your organization have a Risk Register format/template I should follow?
+18. Any existing risks from other projects that apply here?
+
+Please answer these questions so I can generate an accurate risk register.
+```
+
+**Wait for user response.**
+
+---
+
+### Step 2: Generate Risk Register
+
+After user answers, generate risks covering all 5 categories:
+
+**Risk Scoring Matrix:**
+- **Impact** (1-5): 1=Negligible, 2=Minor, 3=Moderate, 4=Major, 5=Catastrophic
+- **Likelihood** (1-5): 1=Rare, 2=Unlikely, 3=Possible, 4=Likely, 5=Almost Certain
+- **Risk Score** = Impact × Likelihood
+- **Rating**: Low (1-4), Medium (5-9), High (10-15), Critical (16-25)
+
+**Structure each Risk as:**
+
+```markdown
+### RISK-{N}: {Title}
+- **Category**: {Technical|Business|Operational|External|Compliance}
+- **Description**: {What could go wrong and why}
+- **Trigger**: {What would cause this risk to materialize}
+- **Consequence**: {What happens if the risk materializes}
+- **Impact**: {1-5} - {Justification}
+- **Likelihood**: {1-5} - {Justification}
+- **Risk Score**: {Impact × Likelihood} ({Low|Medium|High|Critical})
+- **Related Requirements**: {FR-N, NFR-X or "None"}
+- **Mitigation Strategy**: {How to reduce impact or likelihood}
+- **Contingency Plan**: {What to do if risk materializes}
+- **Owner**: {Role responsible for monitoring/mitigation}
+- **Status**: {Open|Mitigating|Accepted|Closed}
+```
+
+---
+
+### Step 3: Category-by-Category Review
+
+Present risks by category for validation:
+
+#### Category 1/5: Technical Risks
+
+```markdown
+## Technical Risks Review
+
+These risks relate to technology choices, architecture, and implementation:
+
+### RISK-T1: {Title}
+{Full risk details as above}
+
+### RISK-T2: {Title}
+{Full risk details as above}
+
+---
+
+**Validation Questions:**
+1. Are there other technical risks I should consider?
+2. Are the impact/likelihood scores accurate?
+3. Are the mitigation strategies realistic?
+
+Your feedback (or 'approve' to continue):
+```
+
+**Wait for response, then continue to next category.**
+
+#### Category 2/5: Business Risks
+
+```markdown
+## Business Risks Review
+
+These risks relate to business value, adoption, and market factors:
+
+### RISK-B1: {Title}
+{Full risk details}
+
+---
+
+**Validation Questions:**
+1. Are there business risks I've missed?
+2. Any concerns about the business impact scoring?
+
+Your feedback:
+```
+
+**Wait for response.**
+
+#### Category 3/5: Operational Risks
+
+```markdown
+## Operational Risks Review
+
+These risks relate to deployment, monitoring, and support:
+
+### RISK-O1: {Title}
+{Full risk details}
+
+---
+
+**Validation Questions:**
+1. Are deployment/operational risks accurately captured?
+2. Any gaps in the mitigation strategies?
+
+Your feedback:
+```
+
+**Wait for response.**
+
+#### Category 4/5: External Risks
+
+```markdown
+## External Risks Review
+
+These risks relate to third-party dependencies and external factors:
+
+### RISK-E1: {Title}
+{Full risk details}
+
+---
+
+**Validation Questions:**
+1. Are all third-party dependencies covered?
+2. Any vendor-specific concerns I should add?
+
+Your feedback:
+```
+
+**Wait for response.**
+
+#### Category 5/5: Compliance Risks
+
+```markdown
+## Compliance Risks Review
+
+These risks relate to regulatory, legal, and audit requirements:
+
+### RISK-C1: {Title}
+{Full risk details}
+
+---
+
+**Validation Questions:**
+1. Are regulatory requirements fully addressed?
+2. Any compliance gaps I've missed?
+
+Your feedback:
+```
+
+**Wait for response.**
+
+---
+
+### Step 4: Risk Summary and Prioritization
+
+Generate risk summary sorted by score:
+
+```markdown
+## Risk Summary
+
+### Critical Risks (Score 16-25) - Immediate attention required
+- **RISK-{N}**: {Title} - Score: {X} - Owner: {Role}
+
+### High Risks (Score 10-15) - Active mitigation required
+- **RISK-{N}**: {Title} - Score: {X} - Owner: {Role}
+
+### Medium Risks (Score 5-9) - Monitor closely
+- **RISK-{N}**: {Title} - Score: {X} - Owner: {Role}
+
+### Low Risks (Score 1-4) - Accept or monitor
+- **RISK-{N}**: {Title} - Score: {X} - Owner: {Role}
+
+### Risk Distribution
+- **Technical**: {count} risks
+- **Business**: {count} risks
+- **Operational**: {count} risks
+- **External**: {count} risks
+- **Compliance**: {count} risks
+
+### Total Risk Score: {sum of all risk scores}
+### Average Risk Score: {average}
+```
+
+---
+
+### Step 5: Document Risk Register
+
+1. **Read Path**: Check `schema.risks` from `.iris/aidlc/memory-bank.yaml`
+   *(Default: `memory-bank/intents/{intent-name}/risks.md`)*
+
+2. **Use Template**: `.iris/aidlc/templates/inception/risks-template.md` (if exists)
+
+3. **Structure**:
+
+   ```markdown
+   ---
+   intent: {intent-name}
+   created: {timestamp}
+   last_updated: {timestamp}
+   total_risks: {count}
+   critical_risks: {count}
+   high_risks: {count}
+   ---
+
+   # Risk Register: {intent-name}
+
+   ## Overview
+   - **Total Risks**: {count}
+   - **Critical (16-25)**: {count}
+   - **High (10-15)**: {count}
+   - **Medium (5-9)**: {count}
+   - **Low (1-4)**: {count}
+
+   ## Technical Risks
+   ### RISK-T1: {Title}
+   {Full details}
+
+   ## Business Risks
+   ### RISK-B1: {Title}
+   {Full details}
+
+   ## Operational Risks
+   ### RISK-O1: {Title}
+   {Full details}
+
+   ## External Risks
+   ### RISK-E1: {Title}
+   {Full details}
+
+   ## Compliance Risks
+   ### RISK-C1: {Title}
+   {Full details}
+
+   ## Mitigation Tracking
+   | Risk ID | Mitigation Action | Owner | Due Date | Status |
+   |---------|------------------|-------|----------|--------|
+   | RISK-T1 | {Action} | {Owner} | {Date} | {Status} |
+
+   ## Risk Register Alignment
+   {Note alignment with organization's Risk Register format, or state "Standalone"}
+   ```
+
+---
+
+### Step 6: Risk Register Review
+
+**Checkpoint 2**: Present FULL risk register for approval.
+
+**CRITICAL: Show complete details. Do NOT summarize.**
+
+```markdown
+### Inception Progress
+- [x] Intent created
+- [x] Requirements gathered
+- [ ] Risks defined ← current (Checkpoint 2: approval)
+- [ ] Artifacts reviewed
+- [ ] Ready for Construction
+
+---
+
+## Complete Risk Register Review
+
+### Summary
+- **Total Risks**: {count}
+- **Critical**: {count} | **High**: {count} | **Medium**: {count} | **Low**: {count}
+
+### Critical & High Risks (Requiring Active Mitigation)
+
+#### RISK-{N}: {Title}
+- **Category**: {Category}
+- **Description**: {full description}
+- **Impact**: {score} | **Likelihood**: {score} | **Risk Score**: {total}
+- **Mitigation**: {strategy}
+- **Owner**: {role}
+
+{Continue for all Critical/High risks...}
+
+### Medium & Low Risks
+
+{List with abbreviated format}
+
+---
+
+Does this risk register capture all known risks?
+1 - **Approve**: Save and continue
+2 - **Revise**: Request changes (specify what)
+```
+
+**Wait for user response.**
+
+---
+
+## Output
+
+```markdown
+## Risk Register Complete: {intent-name}
+
+### Summary
+- **Total Risks**: {N} identified
+- **Critical Risks**: {N} (immediate attention)
+- **High Risks**: {N} (active mitigation)
+- **Medium Risks**: {N} (monitoring)
+- **Low Risks**: {N} (accepted)
+
+### Risk Quality
+- ✅ All risks have impact/likelihood scoring
+- ✅ All Critical/High risks have mitigation plans
+- ✅ All risks have assigned owners
+- ✅ Risks linked to requirements
+
+### Category Coverage
+- ✅ Technical: {count} risks
+- ✅ Business: {count} risks
+- ✅ Operational: {count} risks
+- ✅ External: {count} risks
+- ✅ Compliance: {count} risks
+
+### Artifact Created
+- `{intent-path}/risks.md`
+
+### Actions
+
+1 - **context**: Define system context and boundaries
+2 - **auto-continue**: Batch-generate remaining artifacts
+3 - **menu**: Return to inception menu
+
+### Suggested Next Step
+→ **context** - Define system boundaries for `{intent-name}`
+
+**Type a number or press Enter for suggested action.**
+```
+
+---
+
+## After Approval
+
+Once risks are approved at Checkpoint 2:
+
+1. Save to `{intent}/risks.md`
+2. Update inception-log.md with artifact status
+3. Present transition options to user
+
+---
+
+## Transition
+
+### Inception Phase Flow
+
+After risks defined, the Inception flow continues:
+
+```text
+Requirements
+     ↓
+   Risks ← YOU ARE HERE
+     ↓
+   Context ──────────────────────────┐
+     ↓                               │
+   Units ────────────────────────────┤ Can batch-generate
+     ↓                               │ from here if risks
+   Stories ──────────────────────────┤ are comprehensive
+     ↓                               │
+   Bolt Plan ────────────────────────┘
+     ↓
+   Review All Artifacts (Checkpoint 4)
+     ↓
+   Ready for Construction
+```
+
+### Next Step Options
+
+1 - **context** (Recommended)
+    Define system boundaries and external actors
+    → `.iris/aidlc/skills/inception/context.md`
+    Use if: Complex integrations, many external dependencies
+
+2 - **auto-continue**
+    Batch-generate Context → Units → Stories → Bolt Plan
+    → Executes skills in sequence, reviews all at Checkpoint 4
+    Use if: Risks are comprehensive, rapid iteration needed
+
+3 - **menu**
+    Return to Inception navigator
+    → `.iris/aidlc/skills/inception/navigator.md`
+    Use if: Need to check status or switch intents
+
+### Decision Criteria
+
+- **Choose context if**: Many external systems, complex integrations, brownfield project
+- **Choose auto-continue if**: Greenfield project, clear boundaries, trust AI elaboration
+- **Choose menu if**: Need to review other intents or check overall progress
+
+---
+
+## Risk Monitoring (Post-Inception)
+
+During Construction and Operations, risks should be reviewed:
+
+### Construction Phase
+- Review technical risks before each Bolt
+- Update risk status as mitigations are implemented
+- Add new risks discovered during development
+
+### Operations Phase
+- Review operational risks before deployment
+- Update external/compliance risks as regulations change
+- Close mitigated risks, add new operational risks
+
+---
+
+## Test Contract
+
+```yaml
+input: User answers to risk discovery questions (5 categories)
+output: risks.md with categorized risks, scoring, mitigations, owners
+checkpoints: 2
+  - Checkpoint 1: Risk discovery questions answered
+  - Checkpoint 2: Full risk register approved
+```

package/flows/aidlc/skills/inception/story-create.md

@@ -35,12 +35,13 @@ Show at start of this skill:
 ### Inception Progress
 - [x] Intent created
 - [x] Requirements gathered
+- [x] Risks defined
 - [ ] Generating artifacts...  ← current
     - [x] System Context
     - [x] Units
     - [ ] Stories  ← this skill
     - [ ] Bolt Plan
-- [ ] Artifacts reviewed (Checkpoint 3)
+- [ ] Artifacts reviewed (Checkpoint 4)
 - [ ] Ready for Construction
 ```