@jamie-tam/forge 6.0.0

package/skills/discover-requirements/SKILL.md

@@ -0,0 +1,418 @@
+---
+name: discover-requirements
+description: "Use when raw input (meeting notes, tickets, PRDs, screenshots) needs structuring into requirements with acceptance criteria."
+---
+
+# Discover Requirements
+
+Transform any raw input into structured, actionable requirements documents using **Socratic deep-interview methodology**. Accept meeting notes, emails, screenshots, existing documents, verbal descriptions, voice transcripts, or any other unstructured input and produce formal requirements with user stories, acceptance criteria, and MoSCoW priorities.
+
+**Announce at start:** "I'm using the discover-requirements skill with deep-interview methodology to structure your input into formal requirements."
+
+<HARD-GATE>
+Do NOT proceed to brainstorming, architecture, or any planning skill until:
+1. Requirements have been documented and approved by the user
+2. Ambiguity score is at or below 20% (see Ambiguity Scoring below)
+Every feature starts here or with an explicit user description.
+</HARD-GATE>
+
+---
+
+## I/O Contract
+
+| Field | Value |
+|---|---|
+| **Requires** | Raw input from user (any format: text, images, documents, verbal description) |
+| **Produces** | `.forge/work/{type}/{name}/requirements.md` |
+| **Feeds into** | `plan-brainstorm`, `plan-architecture` |
+| **Updates manifest** | `artifacts.requirements` |
+
+---
+
+## Checklist
+
+Complete these steps in order:
+
+1. **Detect brownfield/greenfield** -- check if existing codebase exists
+2. **Receive and catalog input** -- identify what was provided and its format
+3. **Identify input gaps** -- determine what is missing or ambiguous
+4. **Deep-interview loop** -- Socratic questioning with ambiguity scoring until score ≤ 20%
+5. **Extract requirements** -- pull structured items from the clarified input
+6. **Assign priorities** -- MoSCoW classification for every requirement
+7. **Write acceptance criteria** -- testable criteria for every requirement
+8. **Select output template** -- user stories, PRD, or technical spec
+9. **Draft requirements document** -- write to `.forge/work/{type}/{name}/requirements.md`
+10. **User review and approval** -- present for review, iterate until approved
+11. **Update feature manifest** -- record artifact path and approval status
+
+---
+
+## Process
+
+### Step 0: Detect Brownfield / Greenfield
+
+Before asking the user anything, determine if this is a brownfield (existing code) or greenfield (new project):
+
+```bash
+# Check for existing source code
+ls src/ app/ lib/ packages/ 2>/dev/null
+```
+
+**Brownfield:** Run the `discover-codebase-analysis` skill first (or read existing analysis). Before asking the user questions, explore the codebase to understand existing patterns, auth mechanisms, database schemas, and API conventions. Use evidence-cited questions:
+
+> "I found JWT auth with passport.js in src/auth/. Should this feature extend that middleware or use a different approach?"
+
+This prevents making the user rediscover what the code already tells you.
+
+**Greenfield:** Skip codebase exploration. Proceed directly to input cataloging.
+
+### Step 1: Receive and Catalog Input
+
+Accept ANY input format the user provides:
+
+- **Meeting notes** -- extract action items, decisions, open questions
+- **Emails/messages** -- identify requests, constraints, stakeholder expectations
+- **Screenshots** -- describe what you see, identify UI requirements or issues
+- **Existing documents** -- parse structure, extract relevant requirements
+- **Verbal descriptions** -- capture intent, ask for confirmation of understanding
+- **Voice transcripts** -- clean up, identify key points, separate signal from noise
+- **Code snippets** -- infer the requirement the code is trying to solve
+- **Bug reports** -- extract the expected behavior as a requirement
+
+Summarize what you received back to the user in a brief inventory:
+
+> "I received: [list of inputs]. Let me work through some clarifying questions to make sure I capture everything correctly."
+
+### Step 1.5: Codex Mode Check
+
+Now that the input is cataloged, run the Codex consent flow from `protocols/codex.md`. The selected mode applies for the rest of this skill's invocation.
+
+- **Takeover:** Dispatch Codex with the cataloged input + skill methodology. Claude reviews Codex's draft requirements at the end.
+- **Verify** or **Skip / Codex unavailable:** Proceed with the steps below. The Codex Requirements Verify step will run after Claude's draft (Verify only).
+
+### Step 2: Identify Input Gaps
+
+Before asking questions, internally assess:
+
+- Who are the users/actors?
+- What are the core actions they need to perform?
+- What are the success conditions?
+- What constraints exist (technical, business, time)?
+- What error scenarios need handling?
+- What is explicitly out of scope?
+
+### Step 3: Deep-Interview Loop (Socratic Questioning with Ambiguity Scoring)
+
+This replaces simple clarifying questions with a rigorous, mathematically-gated interview process.
+
+**Core framing: Test assumptions, don't gather features.**
+
+The goal is NOT to ask "what do you want?" — that produces feature lists. Instead, ask "what are you assuming?" — that exposes hidden requirements. Every question should surface and test an assumption rather than accumulate features.
+
+**"No user rediscovery" principle:** If the codebase already tells you something (auth mechanism, database schema, API patterns), do NOT ask the user about it. Explore the code first, then ask the user to CONFIRM or CORRECT, not discover.
+
+#### Ambiguity Scoring
+
+After EVERY user answer, score clarity across weighted dimensions:
+
+**Greenfield projects:**
+
+| Dimension | Weight | Score 0.0-1.0 |
+|---|---|---|
+| Goal Clarity | 40% | How precisely is the desired outcome defined? |
+| Constraint Clarity | 30% | Are boundaries, limitations, and non-goals explicit? |
+| Success Criteria | 30% | Can you write a test from the acceptance criteria? |
+
+**Brownfield projects (existing codebase):**
+
+If `discover-codebase-analysis` has already been completed, use the greenfield weights above — the context dimension is already satisfied. Only use the brownfield weights below when codebase analysis was NOT done:
+
+| Dimension | Weight | Score 0.0-1.0 |
+|---|---|---|
+| Goal Clarity | 35% | How precisely is the desired outcome defined? |
+| Constraint Clarity | 25% | Are boundaries, limitations, and non-goals explicit? |
+| Success Criteria | 25% | Can you write a test from the acceptance criteria? |
+| Context Clarity | 15% | Is the existing system understood enough to modify safely? |
+
+**Calculate ambiguity:**
+- Greenfield: `1 - (goal×0.40 + constraints×0.30 + criteria×0.30)`
+- Brownfield: `1 - (goal×0.35 + constraints×0.25 + criteria×0.25 + context×0.15)`
+
+**Gate rule:** Proceed to Step 4 ONLY when ambiguity ≤ 0.2 (20%). User can force early exit from round 3 onward with a warning.
+
+#### Questioning Rules
+
+- **One question per round.** Never bundle multiple questions.
+- **Target the weakest dimension.** Before each question, identify which clarity dimension scores lowest and explicitly name it:
+  > "Goal clarity is the weakest area right now. Let me ask about that."
+- **Multiple choice preferred** over open-ended when possible. Provide 3-5 options labeled A/B/C/D/E with a description for each.
+- **Include an "Other" option** when the choices might not cover the user's intent.
+- **Build on previous answers** -- each question should reference context from prior answers.
+
+#### Challenge Modes (activate at specific rounds)
+
+| Round | Mode | Focus |
+|---|---|---|
+| 4+ | **Contrarian** | "What if the opposite were true?" -- tests core assumptions |
+| 6+ | **Simplifier** | "What's the minimal viable version?" -- removes assumed complexity |
+| 8+ (if ambiguity > 0.3) | **Ontologist** | "What IS this, really?" -- finds essence by examining core entities |
+
+Each mode activates once per interview, injecting a perspective shift into the question.
+
+#### Ontology Tracking
+
+Track key entities (nouns) and their relationships across rounds:
+
+- **Stable entities:** present in consecutive rounds with same name
+- **Changed entities:** renamed but conceptually identical
+- **New entities:** genuinely new concepts introduced
+
+**Stall detection:** If ambiguity score changes by less than ±0.05 for 3 consecutive rounds, the interview is stalling. Activate Ontologist mode to reframe fundamentals. If already past Ontologist mode, suggest the user provide additional context or accept current clarity level.
+
+#### Progress Reporting
+
+After every 3 rounds (not every single answer — that's noisy), briefly report:
+
+```
+Clarity check (round N): ~XX% clear
+  Strongest: [dimension] | Weakest: [dimension] — focusing here next
+```
+
+Keep it short. The user wants to know progress, not see a dashboard.
+
+#### Limits
+
+- **Round 3+:** User can force early exit with warning about remaining ambiguity
+- **Round 10:** Soft warning — suggest proceeding or continuing
+- **Round 20:** Hard cap — proceed with current clarity, document remaining gaps
+
+### Step 4: Extract Requirements
+
+For each requirement extracted, capture:
+
+- **ID**: REQ-{feature}-{number} (e.g., REQ-PAYMENTS-001)
+- **Title**: Short descriptive name
+- **Description**: What the system must do (not how)
+- **User story**: As a [role], I want [capability], so that [benefit]
+- **Priority**: Must / Should / Could / Won't (MoSCoW)
+- **Acceptance criteria**: Testable conditions (Given/When/Then format)
+- **Source**: Which input this came from (traceability)
+
+### Step 5: Assign Priorities (MoSCoW)
+
+Every requirement gets a priority. Explain the framework to the user if needed:
+
+| Priority | Meaning | Guideline |
+|---|---|---|
+| **Must** | Non-negotiable for this release | System is unusable without it |
+| **Should** | Important but not critical | Workaround exists, or can ship without |
+| **Could** | Desirable if time allows | Nice-to-have, enhances UX |
+| **Won't** | Explicitly excluded this time | Documented for future consideration |
+
+Present priorities to the user for validation. They may reclassify.
+
+### Step 6: Write Acceptance Criteria
+
+Every requirement MUST have at least one acceptance criterion. Use Given/When/Then format:
+
+```
+Given [precondition]
+When [action]
+Then [expected result]
+```
+
+Criteria must be:
+
+- **Testable** -- a developer can write an automated test from this
+- **Specific** -- no vague language ("fast", "user-friendly", "intuitive")
+- **Measurable** -- quantify where possible (response time < 200ms, not "fast")
+- **Independent** -- each criterion can be verified on its own
+
+### Step 7: Select Output Template
+
+Ask the user which format they prefer:
+
+> "Which output format works best for your team?"
+>
+> A) **User Stories** -- Agile-style stories with acceptance criteria (best for dev teams)
+> B) **PRD (Product Requirements Document)** -- Comprehensive product doc (best for stakeholder alignment)
+> C) **Technical Specification** -- Technical focus with system constraints (best for engineering handoff)
+
+Use the corresponding template from `templates/`:
+
+- `user-stories.md`
+- `prd.md`
+- `technical-spec.md`
+
+### Step 8: Draft Requirements Document
+
+Write the complete document to `.forge/work/{type}/{name}/requirements.md`.
+
+The document MUST include these sections regardless of template:
+
+1. **Feature Overview** -- one paragraph summary
+2. **Scope** -- what is in, what is explicitly out
+3. **Users/Actors** -- who interacts with this feature
+4. **Requirements** -- numbered list with all fields from Step 4
+5. **Acceptance Criteria** -- consolidated or per-requirement
+6. **Priorities** -- MoSCoW summary table
+7. **Assumptions** -- assumptions exposed during interview and how they were resolved (e.g., "Assumed offline access needed → tested in round 4, user confirmed NOT needed → removed from scope")
+8. **Open Questions** -- anything still unresolved (must be resolved before brainstorm)
+9. **Dependencies** -- other features, services, or systems this touches
+
+### Step 9: User Review and Approval
+
+Present a summary of the requirements document and ask for explicit approval:
+
+> "Requirements document written to `.forge/work/{type}/{name}/requirements.md`. Here is a summary:
+>
+> - **{N} Must-have requirements**
+> - **{N} Should-have requirements**
+> - **{N} Could-have requirements**
+> - **{N} Won't-have items** (documented for future)
+>
+> Please review the document. Let me know if anything needs to change before we proceed to brainstorming."
+
+Iterate until the user approves. Track revision count.
+
+### Step 10: Update Feature Manifest
+
+After approval, update `.forge/work/{type}/{name}/manifest.yaml`:
+
+```yaml
+artifacts:
+  requirements:
+    path: requirements.md
+    status: approved
+    approved_at: YYYY-MM-DD
+    revision: N
+    requirement_count:
+      must: N
+      should: N
+      could: N
+      wont: N
+```
+
+---
+
+## Date Handling
+
+Convert all relative dates to absolute dates based on the current date:
+
+- "next week" -> specific date
+- "by end of quarter" -> specific date
+- "ASAP" -> flag for priority discussion, do not assign a date
+
+---
+
+## Key Rules
+
+1. **Every requirement MUST have acceptance criteria.** No exceptions. If a requirement cannot have testable criteria, it is not a requirement -- it is a wish.
+2. **Every requirement MUST have a priority.** Unprioritized requirements lead to scope creep.
+3. **No implementation details.** Requirements describe WHAT, not HOW. Architecture decides HOW. If the user provides implementation preferences, capture them in a "Technical Preferences" section but do not let them constrain the requirements.
+4. **Convert relative dates to absolute.** "Next sprint" is meaningless in a document. Use specific dates.
+5. **Trace everything.** Every requirement links back to the source input. This is how you verify completeness.
+6. **Resolve open questions before handoff.** The requirements document that feeds into brainstorm must have zero unresolved questions. If questions remain, flag them and ask the user to resolve.
+
+---
+
+## Anti-Patterns
+
+| Anti-Pattern | Why It Is Wrong | What To Do Instead |
+|---|---|---|
+| **Guessing requirements** | Unvalidated assumptions become bugs | Ask the user. Always. |
+| **Adding features the user did not ask for** | Scope creep wastes time and confuses priorities | Document only what was requested. Suggest additions separately. |
+| **Skipping clarification because "it seems obvious"** | "Obvious" requirements have the most hidden complexity | Ask anyway. The question is cheap; the rework is expensive. |
+| **Combining multiple questions in one message** | Overwhelms the user, leads to partial answers | One question per message. Always. |
+| **Using vague acceptance criteria** | "System should be fast" is untestable | Quantify: "Response time < 200ms at p95 under 100 concurrent users" |
+| **Mixing requirements with solutions** | Constrains the design space prematurely | Capture as "Technical Preferences" but keep requirements solution-agnostic |
+| **Skipping Won't-have items** | Undocumented exclusions become scope disputes later | Explicitly list what is NOT included and why |
+
+---
+
+## Handling Edge Cases
+
+### User provides only a vague idea
+
+Start with scope questions. Help them articulate what they want before trying to extract formal requirements:
+
+> "Let me help you flesh this out. First question: what problem are you trying to solve?"
+
+### User provides an existing spec or PRD
+
+Do not re-extract from scratch. Instead:
+
+1. Parse the existing document
+2. Identify gaps (missing acceptance criteria, unprioritized items, ambiguous language)
+3. Ask targeted questions to fill the gaps
+4. Output in the standardized format
+
+### User provides conflicting requirements
+
+Flag the conflict explicitly:
+
+> "I noticed a potential conflict: Requirement A says [X], but Requirement B implies [Y]. Which takes priority?"
+
+Do not silently resolve conflicts. Surface them for user decision and document the resolution.
+
+### User wants to skip to implementation
+
+Remind them of the process:
+
+> "I understand the urgency, but undocumented requirements lead to rework. Let me ask 3-4 quick clarifying questions to make sure we build the right thing. It will take 2-3 minutes and save hours later."
+
+---
+
+### Codex Requirements Verify 
+After drafting the requirements document, check the mode recorded at Step 1.5. If **Verify** was selected, dispatch Codex to review for completeness gaps, contradictions, and missing edge cases. Present findings to user alongside requirements for review. If **Takeover** was selected, skip this step (Codex already drafted). If **Skip**, do nothing. Do NOT re-run the consent flow. See **Codex Integration** section below for full details.
+
+---
+
+## Output Quality Checklist
+
+Before presenting the document, verify:
+
+- [ ] Every requirement has an ID
+- [ ] Every requirement has acceptance criteria in Given/When/Then format
+- [ ] Every requirement has a MoSCoW priority
+- [ ] No implementation details in requirement descriptions
+- [ ] All relative dates converted to absolute dates
+- [ ] Open questions section is empty (or flagged for resolution)
+- [ ] Dependencies are identified
+- [ ] Scope (in and out) is explicit
+- [ ] Source traceability exists for every requirement
+
+---
+
+## Codex Integration
+**Modes:** Verify or Takeover | **Protocol:** `protocols/codex.md`
+
+- **Verify:** Claude drafts requirements, Codex reviews for completeness.
+- **Takeover:** Codex drafts requirements from user input, Claude reviews and refines.
+
+**When:** After Claude has produced the requirements document and before user approval.
+
+**Context to pass:**
+- Path to `.forge/work/{type}/{name}/requirements.md`
+- Path to `.forge/work/{type}/{name}/codebase-analysis.md` (if available)
+
+**What Codex reviews:**
+- Requirements with missing or vague acceptance criteria
+- Contradictions between requirements
+- Missing edge cases (error states, empty states, concurrent access)
+- Requirements that conflict with existing codebase patterns
+
+**Prompt focus:** "Review this requirements document for completeness gaps, contradictions, and missing edge cases. Flag any requirements that lack testable acceptance criteria."
+
+**Presentation:** Present Codex findings to the user alongside the requirements document for review.
+
+---
+
+## Transition
+
+After the user approves the requirements document:
+
+- If this is a new project or major feature: invoke `plan-brainstorm` to explore approaches
+- If this is a small change with obvious implementation: user may skip to `plan-architecture` or `plan-task-decompose` (but flag that brainstorming was skipped in the manifest)
+
+> "Requirements approved. Next step: brainstorming approaches. I'll use the plan-brainstorm skill to explore 2-3 approaches with you before we commit to an architecture."

package/skills/discover-requirements/templates/prd.md

@@ -0,0 +1,99 @@
+# Product Requirements Document
+
+## 1. Problem Statement
+
+{What problem are we solving? Who has this problem? Why does it matter? What happens if we do not solve it?}
+
+## 2. Goals
+
+- {Goal 1: measurable outcome we want to achieve}
+- {Goal 2: measurable outcome we want to achieve}
+- {Goal 3: measurable outcome we want to achieve}
+
+## 3. Non-Goals
+
+- {Explicitly out of scope item 1 — and why}
+- {Explicitly out of scope item 2 — and why}
+
+## 4. User Personas
+
+### Persona: {Name}
+- **Role**: {Who they are}
+- **Goals**: {What they want to accomplish}
+- **Pain points**: {What frustrates them today}
+- **Technical level**: {Novice / Intermediate / Expert}
+
+### Persona: {Name}
+- **Role**: {Who they are}
+- **Goals**: {What they want to accomplish}
+- **Pain points**: {What frustrates them today}
+- **Technical level**: {Novice / Intermediate / Expert}
+
+## 5. User Journeys
+
+Define the end-to-end flows users perform. Each journey chains multiple requirements into a single testable path. E2E tests are derived from these journeys.
+
+### Journey: {Journey Name}
+**Priority:** Must / Should / Could
+**Persona:** {which persona performs this journey}
+
+| Step | User Does | System Response | Requirements |
+|---|---|---|---|
+| 1 | {user action} | {what the system does in response} | {FR-xxx} |
+| 2 | {user action} | {what the system does in response} | {FR-xxx} |
+| 3 | {user action} | {what the system does in response} | {FR-xxx} |
+
+**Error paths:**
+- At step {N}, if {error condition}: {expected system behavior}
+
+### Journey: {Journey Name}
+**Priority:** Must / Should / Could
+**Persona:** {which persona performs this journey}
+
+| Step | User Does | System Response | Requirements |
+|---|---|---|---|
+| 1 | {user action} | {system response} | {FR-xxx} |
+
+## 6. Requirements
+
+### 6.1 Functional Requirements
+
+| ID | Requirement | Priority | Acceptance Criteria |
+|----|------------|----------|-------------------|
+| FR-001 | {requirement description} | Must | {how to verify it works} |
+| FR-002 | {requirement description} | Should | {how to verify it works} |
+| FR-003 | {requirement description} | Could | {how to verify it works} |
+
+### 6.2 Non-Functional Requirements
+
+| ID | Requirement | Category | Target |
+|----|------------|----------|--------|
+| NFR-001 | {requirement} | Performance | {e.g., p95 latency < 200ms} |
+| NFR-002 | {requirement} | Reliability | {e.g., 99.9% uptime} |
+| NFR-003 | {requirement} | Security | {e.g., SOC2 compliant} |
+| NFR-004 | {requirement} | Scalability | {e.g., support 10k concurrent users} |
+| NFR-005 | {requirement} | Accessibility | {e.g., WCAG 2.1 AA} |
+
+## 7. Success Metrics
+
+| Metric | Current Baseline | Target | Measurement Method |
+|--------|-----------------|--------|-------------------|
+| {metric name} | {current value or N/A} | {target value} | {how we measure} |
+| {metric name} | {current value or N/A} | {target value} | {how we measure} |
+
+## 8. Timeline
+
+| Milestone | Target Date | Dependencies |
+|-----------|------------|-------------|
+| Requirements finalized | {date} | Stakeholder approval |
+| Architecture approved | {date} | Requirements |
+| MVP complete | {date} | Architecture |
+| Testing complete | {date} | MVP |
+| Launch | {date} | Testing |
+
+## 9. Open Questions
+
+| # | Question | Owner | Status | Answer |
+|---|---------|-------|--------|--------|
+| 1 | {question that needs to be resolved} | {who decides} | Open | — |
+| 2 | {question that needs to be resolved} | {who decides} | Resolved | {answer} |

package/skills/discover-requirements/templates/technical-spec.md

@@ -0,0 +1,123 @@
+# Technical Specification
+
+## 1. Overview
+
+**Feature/Project**: {name}
+**Author**: {name}
+**Date**: {date}
+**Status**: Draft / In Review / Approved
+
+### Summary
+{One paragraph describing what this technical spec covers and why.}
+
+### Background
+{Context needed to understand this spec. What exists today? What prompted this work?}
+
+## 2. Architecture
+
+### System Context
+{How does this feature/system fit into the broader architecture? What systems does it interact with?}
+
+### Component Design
+{Describe the major components, their responsibilities, and how they interact.}
+
+```
+┌─────────────┐     ┌─────────────┐     ┌─────────────┐
+│ Component A │────>│ Component B │────>│ Component C │
+└──────┬──────┘     └─────────────┘     └─────────────┘
+       │
+       v
+┌─────────────┐
+│ Component D │
+└─────────────┘
+```
+
+### Key Design Decisions
+{Describe important design decisions and the reasoning behind them. For significant decisions, create a separate ADR.}
+
+| Decision | Choice | Rationale | Alternatives Considered |
+|----------|--------|-----------|------------------------|
+| {what was decided} | {what was chosen} | {why} | {what else was considered} |
+
+## 3. API Design
+
+### Endpoint: {METHOD} {/path}
+
+**Description**: {what this endpoint does}
+**Authentication**: {required/optional/none}
+
+**Request**:
+```json
+{
+  "field": "type — description"
+}
+```
+
+**Response (200)**:
+```json
+{
+  "field": "type — description"
+}
+```
+
+**Error Responses**:
+| Status | Code | Description |
+|--------|------|-------------|
+| 400 | INVALID_INPUT | {when this occurs} |
+| 401 | UNAUTHORIZED | {when this occurs} |
+| 404 | NOT_FOUND | {when this occurs} |
+
+## 4. Data Model
+
+### Table: {table_name}
+{Description of what this table stores.}
+
+| Column | Type | Nullable | Default | Description |
+|--------|------|----------|---------|-------------|
+| id | UUID | No | gen_random_uuid() | Primary key |
+| {column} | {type} | {Yes/No} | {default} | {description} |
+| created_at | TIMESTAMP | No | now() | Record creation time |
+| updated_at | TIMESTAMP | No | now() | Last update time |
+
+**Indexes**: {index definitions}
+**Foreign Keys**: {FK relationships}
+
+### Migration Plan
+{How to migrate from the current schema to the new schema. Include data migration if needed.}
+
+## 5. Security Considerations
+
+- **Authentication**: {how users are authenticated for this feature}
+- **Authorization**: {what permissions are required, how they are enforced}
+- **Data sensitivity**: {what sensitive data is handled, how it is protected}
+- **Input validation**: {what inputs are validated and how}
+- **Audit logging**: {what actions are logged}
+
+## 6. Testing Strategy
+
+| Test Type | What It Covers | Tools |
+|-----------|---------------|-------|
+| Unit | {individual functions, edge cases} | {test runner} |
+| Integration | {component interactions, API contracts} | {test runner} |
+| E2E | {user flows, browser interactions} | {Playwright} |
+| Performance | {load, latency, throughput} | {k6/artillery} |
+
+### Key Test Scenarios
+- {Scenario 1: description}
+- {Scenario 2: description}
+- {Scenario 3: description}
+
+## 7. Deployment Plan
+
+- **Deploy strategy**: {rolling/blue-green/canary}
+- **Feature flags**: {any feature flags needed}
+- **Rollback plan**: {how to rollback if something goes wrong}
+- **Monitoring**: {what to monitor after deploy}
+- **Runbook**: {link to runbook or inline steps for common issues}
+
+## 8. Risks and Mitigations
+
+| Risk | Likelihood | Impact | Mitigation |
+|------|-----------|--------|------------|
+| {what could go wrong} | Low/Med/High | Low/Med/High | {how to prevent or handle it} |
+| {what could go wrong} | Low/Med/High | Low/Med/High | {how to prevent or handle it} |