project-iris 0.0.16 → 0.0.17

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

@@ -4,26 +4,46 @@
 
 ## 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 checkpoint moments
-- ✅ **ALWAYS** present FULL requirements at Checkpoint 2 (no summaries)
-- 🛑 **STOP** at Checkpoint 1 (questions) and Checkpoint 2 (approval)
+- ✅ **ALWAYS** ask clarifying questions BEFORE generating anything
+- ✅ **ALWAYS** present FULL requirements at review (no summaries)
+- 🛑 **STOP** at each checkpoint - wait for user response
+
+### Functional Requirements Rules
+- ✅ **ALWAYS** start with user/goal clarification before listing FRs
+- ✅ **ALWAYS** include User Story format: "As a {user}, I want {action} so that {benefit}"
+- ✅ **ALWAYS** include testable Acceptance Criteria (binary pass/fail)
+- ✅ **ALWAYS** assign Priority (Must/Should/Could)
+- ✅ **ALWAYS** identify dependencies between FRs
+
+### Non-Functional Requirements Rules
+- ✅ **ALWAYS** walk through ALL 5 NFR categories (Performance, Scalability, Security, Reliability, Compliance)
+- ✅ **ALWAYS** ensure NFRs have measurable metrics (not vague)
+- ✅ **ALWAYS** define SLOs for critical requirements
+- ✅ **ALWAYS** document trade-offs when NFRs conflict
 
 ## Success Metrics
 
 - ✅ Clarifying questions asked before generating
-- ✅ Full requirements shown at review (not summarized)
-- ✅ Each requirement has: Description, Acceptance Criteria, Priority
-- ✅ Clear approval prompt at Checkpoint 2
+- ✅ Each FR has: User Story, Acceptance Criteria, Priority, Dependencies
+- ✅ All 5 NFR categories addressed
+- ✅ Each NFR has: Category, Requirement, Metric, Target
+- ✅ SLOs defined for critical requirements
+- ✅ Trade-offs documented when requirements conflict
 
 ## Failure Modes
 
-- ❌ Using ASCII table for checkpoints
 - ❌ Generating requirements without asking questions first
-- ❌ Summarizing requirements at review instead of full details
-- ❌ Not waiting for approval at checkpoints
+- ❌ FRs without testable acceptance criteria
+- ❌ FRs without user story format
+- ❌ Vague NFRs without metrics (e.g., "must be fast", "must be secure")
+- ❌ Skipping NFR categories without explicit user confirmation
+- ❌ Summarizing at review instead of showing full details
+- ❌ Not documenting trade-offs between conflicting requirements
 
 ---
 
@@ -41,18 +61,17 @@ Show at start of this skill:
 
 ---
 
-## Checkpoints in This Skill
+## Checkpoints
 
-| Checkpoint | Purpose | Wait For |
-|------------|---------|----------|
-| Checkpoint 1 | Clarifying questions | User answers |
-| Checkpoint 2 | Requirements review | User approval |
+- **Checkpoint 1**: Clarifying questions for Functional Requirements
+- **Checkpoint 2**: NFR category discovery (5 categories)
+- **Checkpoint 3**: Full requirements review and approval
 
 ---
 
 ## Goal
 
-Elicit, analyze, and document functional and non-functional requirements through structured inquiry.
+Elicit, analyze, and document functional and non-functional requirements through structured inquiry, following AI-DLC's comprehensive approach.
 
 ---
 
@@ -68,45 +87,267 @@ Elicit, analyze, and document functional and non-functional requirements through
 
 ## Process
 
-### Step 1: Clarifying Questions
+### Step 1: Functional Requirements Discovery
 
-**Checkpoint 1**: Present questions before generating anything:
+**Checkpoint 1**: Ask clarifying questions BEFORE generating anything.
+
+```markdown
+## Functional Requirements Discovery
 
-```text
 Before I generate requirements, I need to understand:
-1. Who are the primary users?
-2. What key outcomes matter?
-3. Any constraints (regulatory, technical, timeline)?
-4. How will we measure success?
-5. What concerns you most?
+
+### Users & Goals
+1. Who are the primary users of this feature?
+2. What problem does this solve for them?
+3. What key outcomes/success metrics matter?
+
+### Scope & Boundaries
+4. What are the main user flows/actions?
+5. What is explicitly OUT of scope?
+
+### Constraints
+6. Any regulatory/compliance requirements?
+7. Any technical constraints or dependencies?
+8. Timeline or budget constraints?
+
+### Concerns
+9. What concerns you most about this feature?
+10. Any known risks or unknowns?
+
+Please answer these questions so I can generate accurate requirements.
 ```
 
 **Wait for user response.**
 
 ---
 
-### Step 2: Generate Requirements
+### Step 2: Generate Functional Requirements
+
+After user answers, generate FRs covering:
+
+- **Core Functionality**: Main user flows from answers
+- **Data Requirements**: What data is created, stored, retrieved
+- **Integration Points**: External systems, APIs
+- **Error Handling**: Edge cases, failure scenarios
+- **Business Rules**: Validation, constraints
+
+**Structure each FR as:**
+
+```markdown
+### FR-{N}: {Title}
+- **User Story**: As a {user}, I want {action} so that {benefit}
+- **Description**: {Detailed explanation of what the system must do}
+- **Acceptance Criteria**:
+  - [ ] {Testable criterion 1 - binary pass/fail}
+  - [ ] {Testable criterion 2 - binary pass/fail}
+  - [ ] {Testable criterion 3 - binary pass/fail}
+- **Priority**: Must/Should/Could
+- **Dependencies**: {Other FRs, external systems, or "None"}
+```
+
+---
+
+### Step 3: NFR Category Discovery
+
+**Checkpoint 2**: Walk through each NFR category with targeted questions.
+
+Present each category one at a time:
+
+#### Category 1: Performance
+
+```markdown
+## NFR Category 1/5: Performance
+
+1. **Response Time**: What's acceptable for main operations?
+   - 1 - Fast (< 100ms) - Real-time feel
+   - 2 - Standard (< 500ms) - Typical web app
+   - 3 - Tolerant (< 2s) - Complex operations
+   - 4 - Specify custom target
+
+2. **Throughput**: Expected request volume?
+   - Requests per second: ___
+   - Peak vs normal ratio: ___
+
+3. **Latency-sensitive operations**: Any operations needing special attention?
+
+Your answers (or 'skip' if not applicable):
+```
+
+**Wait for response, then continue to next category.**
+
+#### Category 2: Scalability
+
+```markdown
+## NFR Category 2/5: Scalability
+
+1. **Current Load**:
+   - Expected daily active users: ___
+   - Peak concurrent users: ___
+   - Data volume (records): ___
+
+2. **Growth** (next 12 months):
+   - 1 - Low (< 2x growth)
+   - 2 - Medium (2-5x growth)
+   - 3 - High (5-10x growth)
+   - 4 - Hyper (> 10x growth)
+
+3. **Scaling Strategy**:
+   - 1 - Horizontal (add instances)
+   - 2 - Vertical (larger instances)
+   - 3 - Auto-scaling (dynamic)
+   - 4 - Need recommendation
+
+Your answers:
+```
+
+**Wait for response.**
+
+#### Category 3: Security
+
+```markdown
+## NFR Category 3/5: Security
+
+1. **Authentication**:
+   - 1 - OAuth 2.0 / OIDC (social/enterprise SSO)
+   - 2 - JWT (stateless tokens)
+   - 3 - Session-based (traditional)
+   - 4 - API Keys (service-to-service)
+   - 5 - None (public access)
+   - 6 - Inherit from project standards
+
+2. **Authorization**:
+   - 1 - RBAC (role-based)
+   - 2 - ABAC (attribute-based)
+   - 3 - Simple (admin/user)
+   - 4 - None needed
+
+3. **Data Sensitivity**:
+   - 1 - Public (no sensitive data)
+   - 2 - Internal (business data)
+   - 3 - Confidential (PII, financial)
+   - 4 - Regulated (HIPAA, PCI-DSS)
+
+4. **Encryption**:
+   - At rest required? (yes/no)
+   - In transit required? (yes/no, default: yes)
+
+Your answers:
+```
+
+**Wait for response.**
+
+#### Category 4: Reliability
+
+```markdown
+## NFR Category 4/5: Reliability
+
+1. **Availability Target**:
+   - 1 - 99.0% (~3.6 days downtime/year) - Internal tools
+   - 2 - 99.9% (~8.7 hours/year) - Standard apps
+   - 3 - 99.95% (~4.4 hours/year) - Business critical
+   - 4 - 99.99% (~52 min/year) - Mission critical
+
+2. **Recovery**:
+   - RTO (time to recover): ___
+   - RPO (acceptable data loss): ___
+
+3. **Failure Handling**:
+   - Graceful degradation needed? (yes/no)
+   - Which features can degrade?
+
+4. **Backup**:
+   - Frequency: ___
+   - Retention period: ___
+
+Your answers:
+```
+
+**Wait for response.**
+
+#### Category 5: Compliance
+
+```markdown
+## NFR Category 5/5: Compliance
+
+1. **Regulatory Requirements** (select all that apply):
+   - 1 - GDPR (EU data protection)
+   - 2 - HIPAA (healthcare - US)
+   - 3 - PCI-DSS (payment cards)
+   - 4 - SOC 2 (service controls)
+   - 5 - SOX (financial - US)
+   - 6 - None specific
+   - 7 - Other: ___
+
+2. **Audit Requirements**:
+   - Audit logging needed? (yes/no)
+   - Log retention period: ___
+   - Immutable logs required? (yes/no)
+
+3. **Data Residency**:
+   - Geographic restrictions? (yes/no)
+   - Allowed regions: ___
+
+Your answers:
+```
+
+**Wait for response.**
+
+---
+
+### Step 4: Define SLOs
+
+Based on NFR answers, define Service Level Objectives:
+
+```markdown
+## Service Level Objectives (SLOs)
+
+Based on your requirements, here are the proposed SLOs:
+
+### Availability SLO
+- **Indicator**: % of successful requests (non-5xx)
+- **Target**: {X}% over 30-day window
+- **Error Budget**: {Y} minutes/month
+
+### Latency SLO
+- **Indicator**: Response time at p95
+- **Target**: < {X}ms
+- **Scope**: All API endpoints
+
+### Error Rate SLO
+- **Indicator**: % of failed requests
+- **Target**: < {X}%
+- **Window**: 24-hour rolling
+
+Do these SLOs align with your expectations?
+1 - **Yes**: Continue
+2 - **Adjust**: Modify targets
+```
+
+---
+
+### Step 5: Document Trade-offs
 
-After user answers, generate functional and non-functional requirements.
+If requirements conflict, document trade-offs:
 
-**Functional Requirements** - ask about:
+```markdown
+## Requirements Trade-offs
 
-- Main user flows → Core functionality
-- Error cases → Exception handling
-- Data storage → Data requirements
-- Integrations → External dependencies
+I've identified these trade-offs in your requirements:
 
-**Non-Functional Requirements** - ask about:
+### Trade-off 1: {e.g., Performance vs Security}
+- **Conflict**: {Description}
+- **Options**:
+  1 - {Option A with implications}
+  2 - {Option B with implications}
+- **Recommendation**: {Your recommendation}
+- **Your decision**: ___
 
-- Performance: Response time, throughput
-- Scalability: Concurrent users, growth
-- Security: Authentication, data sensitivity
-- Reliability: Uptime, failure tolerance
-- Compliance: Regulatory, audit
+{Repeat for other trade-offs}
+```
 
-**IMPORTANT**: Do NOT duplicate project standards. Only document intent-specific constraints.
+---
 
-### Step 3: Document Requirements
+### Step 6: Document Requirements
 
 1. **Read Path**: Check `schema.requirements` from `.iris/aidlc/memory-bank.yaml`
    *(Default: `memory-bank/intents/{intent-name}/requirements.md`)*
@@ -117,101 +358,165 @@ After user answers, generate functional and non-functional requirements.
 
    ```markdown
    ## Functional Requirements
+
    ### FR-1: {Title}
+   - **User Story**: As a {user}, I want {action} so that {benefit}
    - **Description**: {What the system must do}
-   - **Acceptance Criteria**: {Measurable conditions}
+   - **Acceptance Criteria**:
+     - [ ] {Testable criterion 1}
+     - [ ] {Testable criterion 2}
    - **Priority**: {Must/Should/Could}
+   - **Dependencies**: {Other FRs or "None"}
 
    ## Non-Functional Requirements
-   ### NFR-1: Performance
-   - **Metric**: Response time < 200ms for 95th percentile
+
+   ### Performance
+   - **NFR-P1**: Response time p95 < {X}ms
+   - **NFR-P2**: Throughput > {X} req/s
+
+   ### Scalability
+   - **NFR-S1**: Support {X} concurrent users
+
+   ### Security
+   - **NFR-SEC1**: {Authentication method}
+   - **NFR-SEC2**: {Authorization model}
+
+   ### Reliability
+   - **NFR-R1**: {X}% availability
+   - **NFR-R2**: RTO < {X}, RPO < {Y}
+
+   ### Compliance
+   - **NFR-C1**: {Regulatory requirements}
+
+   ## SLOs
+   - **Availability**: {X}%
+   - **Latency (p95)**: < {X}ms
+   - **Error Rate**: < {X}%
+
+   ## Trade-off Decisions
+   - {Trade-off 1}: Chose {option} because {reason}
    ```
 
 4. **Validate Testability**:
    - ❌ "Fast response" → ✅ "Response < 200ms p95"
    - ❌ "Secure" → ✅ "OAuth 2.0 with MFA"
    - ❌ "Scalable" → ✅ "Support 10K concurrent users"
+   - ❌ "User can manage data" → ✅ "User can create, read, update, delete records"
 
 ---
 
-### Step 4: Requirements Review
-
-**Checkpoint 2**: Present FULL requirements for approval.
+### Step 7: Requirements Review
 
-**CRITICAL: Do NOT summarize. Show complete details for each requirement.**
+**Checkpoint 3**: Present FULL requirements for approval.
 
-**Show progress indicator before requirements:**
+**CRITICAL: Show complete details. Do NOT summarize.**
 
-```text
+```markdown
 ### Inception Progress
 - [x] Intent created
-- [ ] Requirements gathered ← current (Checkpoint 2: approval)
-- [ ] Artifacts reviewed (Context + Units + Stories + Bolts)
+- [ ] Requirements gathered ← current (Checkpoint 3: approval)
+- [ ] Artifacts reviewed
 - [ ] Ready for Construction
-```
 
-Present exactly as documented:
-
-```text
-### Requirements Review
+---
 
-## Functional Requirements
+## Complete Requirements Review
 
-### FR-1: {Title}
-- **Description**: {full description}
-- **Acceptance Criteria**: {all criteria}
-- **Priority**: {Must/Should/Could}
+### Functional Requirements
 
-### FR-2: {Title}
+#### FR-1: {Title}
+- **User Story**: As a {user}, I want {action} so that {benefit}
 - **Description**: {full description}
-- **Acceptance Criteria**: {all criteria}
+- **Acceptance Criteria**:
+  - [ ] {criterion 1}
+  - [ ] {criterion 2}
 - **Priority**: {Must/Should/Could}
+- **Dependencies**: {list or "None"}
 
-{continue for all FR and NFR...}
+{Continue for all FRs...}
 
 ---
 
-Do these requirements capture your intent?
-1 - Yes, continue to generate artifacts
-2 - Need changes (specify what's missing/wrong)
-```
+### Non-Functional Requirements
 
-**Wait for user response.**
+#### Performance
+- **NFR-P1**: Response time p95 < {X}ms
+- **NFR-P2**: Throughput > {X} req/s
 
----
+#### Scalability
+- **NFR-S1**: Support {X} concurrent users
+- **NFR-S2**: Scale to {X}x load within {Y} minutes
 
-## Output
+#### Security
+- **NFR-SEC1**: {Authentication method}
+- **NFR-SEC2**: {Authorization model}
+- **NFR-SEC3**: Data encryption {details}
 
-```markdown
-## Requirements Summary: {intent-name}
+#### Reliability
+- **NFR-R1**: {X}% availability
+- **NFR-R2**: RTO < {X}, RPO < {Y}
 
-### Functional Requirements
+#### Compliance
+- **NFR-C1**: {Regulatory requirements}
+- **NFR-C2**: Audit logs retained {X} days
 
-- [ ] **FR-1**: {description} - Priority: Must - Status: Draft
-- [ ] **FR-2**: {description} - Priority: Should - Status: Draft
+---
 
-### Non-Functional Requirements
+### SLOs
+- **Availability**: {X}%
+- **Latency (p95)**: < {X}ms
+- **Error Rate**: < {X}%
 
-- **Performance**: Response time < 200ms p95
-- **Security**: OAuth 2.0 + MFA
+### Trade-off Decisions
+- {Trade-off 1}: Chose {option} because {reason}
 
-### Technical Constraints
+---
 
-Required standards will be loaded from memory-bank standards folder by Construction Agent.
+Do these requirements capture your intent?
+1 - **Approve**: Save and continue
+2 - **Revise**: Request changes (specify what)
+```
 
-Intent-specific constraints:
-- {any feature-specific constraint not in standards}
+**Wait for user response.**
 
-### Artifact Updated
+---
+
+## Output
+
+```markdown
+## Requirements Complete: {intent-name}
+
+### Summary
+- **Functional Requirements**: {N} defined
+- **Non-Functional Requirements**: {N} across 5 categories
+- **SLOs**: {N} defined
+- **Trade-offs**: {N} documented
+
+### FR Quality
+- ✅ All FRs have User Story format
+- ✅ All FRs have testable Acceptance Criteria
+- ✅ All FRs have Priority assigned
+- ✅ Dependencies mapped
+
+### NFR Coverage
+- ✅ Performance: {count} requirements
+- ✅ Scalability: {count} requirements
+- ✅ Security: {count} requirements
+- ✅ Reliability: {count} requirements
+- ✅ Compliance: {count} requirements
+
+### Artifact Created
 - `{intent-path}/requirements.md`
 
 ### Actions
 
-1 - **context**: Define system context and boundaries
-2 - **menu**: Return to inception menu
+1 - **risks**: Define risk register for this intent
+2 - **context**: Define system context and boundaries
+3 - **auto-continue**: Batch-generate remaining artifacts
+4 - **menu**: Return to inception menu
 
 ### Suggested Next Step
-→ **context** - Define system boundaries for `{intent-name}`
+→ **risks** - Identify and document risks for `{intent-name}`
 
 **Type a number or press Enter for suggested action.**
 ```
@@ -220,33 +525,75 @@ Intent-specific constraints:
 
 ## After Approval
 
-Once requirements are approved at Checkpoint 2:
+Once requirements are approved at Checkpoint 3:
 
 1. Save to `{intent}/requirements.md`
 2. Update inception-log.md with artifact status
-3. Proceed to generate remaining artifacts (Context + Units + Stories + Bolts)
+3. Present transition options to user
 
 ---
 
 ## Transition
 
-After requirements approved → Generate batched artifacts:
+### Inception Phase Flow
+
+After requirements approved, the Inception flow continues:
+
+```text
+Requirements ← YOU ARE HERE
+     ↓
+   Risks (recommended) ─────────────┐
+     ↓                              │
+   Context ──────────────────────── │ ─→ Can batch-generate
+     ↓                              │     from here if
+   Units ───────────────────────────┤     requirements are
+     ↓                              │     comprehensive
+   Stories ─────────────────────────┤
+     ↓                              │
+   Bolt Plan ───────────────────────┘
+     ↓
+   Review All Artifacts (Checkpoint 4)
+     ↓
+   Ready for Construction
+```
+
+### Next Step Options
+
+1 - **risks** (Recommended)
+    Define risk register before proceeding
+    → `.iris/aidlc/skills/inception/risks.md`
+    Use if: Regulatory concerns, complex integrations, unknowns identified
+
+2 - **context**
+    Define system boundaries and external actors
+    → `.iris/aidlc/skills/inception/context.md`
+    Use if: Risks already covered in project standards
+
+3 - **auto-continue**
+    Batch-generate Context → Units → Stories → Bolt Plan
+    → Executes skills in sequence, reviews all at Checkpoint 4
+    Use if: Rapid iteration needed, will review all artifacts together
+
+4 - **menu**
+    Return to Inception navigator
+    → `.iris/aidlc/skills/inception/navigator.md`
+    Use if: Need to check status or switch intents
 
-- System Context
-- Units
-- Stories
-- Bolt Plan
+### Decision Criteria
 
-These will be reviewed together at Checkpoint 3 (Artifacts Review).
+- **Choose risks if**: Compliance requirements exist, external dependencies identified, concerns flagged in requirements discovery
+- **Choose context if**: Simple feature with clear boundaries, risks already in project standards
+- **Choose auto-continue if**: Comprehensive requirements captured, trust AI elaboration, will review carefully at Checkpoint 4
 
 ---
 
 ## Test Contract
 
 ```yaml
-input: User answers to 5 clarifying questions
-output: requirements.md with FR-1..n, NFR-1..n
-checkpoints: 2
-  - Checkpoint 1: Clarifying questions answered
-  - Checkpoint 2: Requirements approved
+input: User answers to FR questions + NFR category questions (5 categories)
+output: requirements.md with FRs (user stories, acceptance criteria), NFRs (5 categories), SLOs, trade-offs
+checkpoints: 3
+  - Checkpoint 1: FR clarifying questions answered
+  - Checkpoint 2: All 5 NFR categories addressed
+  - Checkpoint 3: Full requirements approved
 ```