bmad-method 6.0.0-alpha.0 → 6.0.0-alpha.2

package/src/modules/bmm/workflows/4-implementation/correct-course/instructions.md

@@ -1,42 +1,43 @@
 # Correct Course - Sprint Change Management Instructions
 
-<critical>The workflow execution engine is governed by: {project-root}/bmad/core/tasks/workflow.md</critical>
+<critical>The workflow execution engine is governed by: {project-root}/bmad/core/tasks/workflow.xml</critical>
 <critical>You MUST have already loaded and processed: {project-root}/bmad/bmm/workflows/4-implementation/correct-course/workflow.yaml</critical>
+<critical>Communicate all responses in {communication_language} and language MUST be tailored to {user_skill_level}</critical>
+<critical>Generate all documents in {document_output_language}</critical>
+
+<critical>DOCUMENT OUTPUT: Updated epics, stories, or PRD sections. Clear, actionable changes. User skill level ({user_skill_level}) affects conversation style ONLY, not document updates.</critical>
 
 <workflow>
 
 <step n="1" goal="Initialize Change Navigation">
-<action>Confirm change trigger and gather user description of the issue</action>
-<action>Ask: "What specific issue or change has been identified that requires navigation?"</action>
-<action>Verify access to required project documents:</action>
-  - PRD (Product Requirements Document)
-  - Current Epics and Stories
-  - Architecture documentation
-  - UI/UX specifications
-<action>Ask user for mode preference:</action>
-  - **Incremental** (recommended): Refine each edit collaboratively
-  - **Batch**: Present all changes at once for review
-<action>Store mode selection for use throughout workflow</action>
-
-<check>If change trigger is unclear:</check>
-<action>HALT: "Cannot navigate change without clear understanding of the triggering issue. Please provide specific details about what needs to change and why."</action>
-
-<check>If core documents are unavailable:</check>
-<action>HALT: "Need access to project documents (PRD, Epics, Architecture, UI/UX) to assess change impact. Please ensure these documents are accessible."</action>
+  <action>Confirm change trigger and gather user description of the issue</action>
+  <action>Ask: "What specific issue or change has been identified that requires navigation?"</action>
+  <action>Verify access to required project documents:</action>
+    - PRD (Product Requirements Document)
+    - Current Epics and Stories
+    - Architecture documentation
+    - UI/UX specifications
+  <action>Ask user for mode preference:</action>
+    - **Incremental** (recommended): Refine each edit collaboratively
+    - **Batch**: Present all changes at once for review
+  <action>Store mode selection for use throughout workflow</action>
+
+<action if="change trigger is unclear">HALT: "Cannot navigate change without clear understanding of the triggering issue. Please provide specific details about what needs to change and why."</action>
+
+<action if="core documents are unavailable">HALT: "Need access to project documents (PRD, Epics, Architecture, UI/UX) to assess change impact. Please ensure these documents are accessible."</action>
 </step>
 
 <step n="2" goal="Execute Change Analysis Checklist">
-<action>Load and execute the systematic analysis from: {project-root}/bmad/bmm/workflows/4-implementation/correct-course/checklist.md</action>
-<action>Work through each checklist section interactively with the user</action>
-<action>Record status for each checklist item:</action>
-  - [x] Done - Item completed successfully
-  - [N/A] Skip - Item not applicable to this change
-  - [!] Action-needed - Item requires attention or follow-up
-<action>Maintain running notes of findings and impacts discovered</action>
-<action>Present checklist progress after each major section</action>
-
-<check>If checklist cannot be completed:</check>
-<action>Identify blocking issues and work with user to resolve before continuing</action>
+  <action>Load and execute the systematic analysis from: {checklist}</action>
+  <action>Work through each checklist section interactively with the user</action>
+  <action>Record status for each checklist item:</action>
+    - [x] Done - Item completed successfully
+    - [N/A] Skip - Item not applicable to this change
+    - [!] Action-needed - Item requires attention or follow-up
+  <action>Maintain running notes of findings and impacts discovered</action>
+  <action>Present checklist progress after each major section</action>
+
+<action if="checklist cannot be completed">Identify blocking issues and work with user to resolve before continuing</action>
 </step>
 
 <step n="3" goal="Draft Specific Change Proposals">
@@ -81,13 +82,14 @@
 - Show wireframe or flow changes needed
 - Connect changes to user experience impact
 
-<check>If mode is Incremental:</check>
-<action>Present each edit proposal individually</action>
-<ask>Review and refine this change? Options: Approve [a], Edit [e], Skip [s]</ask>
-<action>Iterate on each proposal based on user feedback</action>
+<check if="mode is Incremental">
+  <action>Present each edit proposal individually</action>
+  <ask>Review and refine this change? Options: Approve [a], Edit [e], Skip [s]</ask>
+  <action>Iterate on each proposal based on user feedback</action>
+</check>
+
+<action if="mode is Batch">Collect all edit proposals and present together at end of step</action>
 
-<check>If mode is Batch:</check>
-<action>Collect all edit proposals and present together at end of step</action>
 </step>
 
 <step n="4" goal="Generate Sprint Change Proposal">
@@ -131,6 +133,7 @@
 - Define success criteria for implementation
 
 <action>Present complete Sprint Change Proposal to user</action>
+<action>Write Sprint Change Proposal document to {default_output_file}</action>
 <ask>Review complete proposal. Continue [c] or Edit [e]?</ask>
 </step>
 
@@ -138,15 +141,17 @@
 <action>Get explicit user approval for complete proposal</action>
 <ask>Do you approve this Sprint Change Proposal for implementation? (yes/no/revise)</ask>
 
-<check>If no or revise:</check>
-<action>Gather specific feedback on what needs adjustment</action>
-<action>Return to appropriate step to address concerns</action>
-<goto step="3">If changes needed to edit proposals</goto>
-<goto step="4">If changes needed to overall proposal structure</goto>
+<check if="no or revise">
+  <action>Gather specific feedback on what needs adjustment</action>
+  <action>Return to appropriate step to address concerns</action>
+  <goto step="3">If changes needed to edit proposals</goto>
+  <goto step="4">If changes needed to overall proposal structure</goto>
+
+</check>
 
-<check>If yes:</check>
-<action>Finalize Sprint Change Proposal document</action>
-<action>Determine change scope classification:</action>
+<check if="yes the proposal is approved by the user">
+  <action>Finalize Sprint Change Proposal document</action>
+  <action>Determine change scope classification:</action>
 
 - **Minor**: Can be implemented directly by development team
 - **Moderate**: Requires backlog reorganization and PO/SM coordination
@@ -154,20 +159,26 @@
 
 <action>Provide appropriate handoff based on scope:</action>
 
-<check>If Minor scope:</check>
-<action>Route to: Development team for direct implementation</action>
-<action>Deliverables: Finalized edit proposals and implementation tasks</action>
+</check>
 
-<check>If Moderate scope:</check>
-<action>Route to: Product Owner / Scrum Master agents</action>
-<action>Deliverables: Sprint Change Proposal + backlog reorganization plan</action>
+<check if="Minor scope">
+  <action>Route to: Development team for direct implementation</action>
+  <action>Deliverables: Finalized edit proposals and implementation tasks</action>
+</check>
 
-<check>If Major scope:</check>
-<action>Route to: Product Manager / Solution Architect</action>
-<action>Deliverables: Complete Sprint Change Proposal + escalation notice</action>
+<check if="Moderate scope">
+  <action>Route to: Product Owner / Scrum Master agents</action>
+  <action>Deliverables: Sprint Change Proposal + backlog reorganization plan</action>
+</check>
+
+<check if="Major scope">
+  <action>Route to: Product Manager / Solution Architect</action>
+  <action>Deliverables: Complete Sprint Change Proposal + escalation notice</action>
 
 <action>Confirm handoff completion and next steps with user</action>
 <action>Document handoff in workflow execution log</action>
+</check>
+
 </step>
 
 <step n="6" goal="Workflow Completion">
@@ -183,7 +194,7 @@
 - Specific edit proposals with before/after
 - Implementation handoff plan
 
-<action>Report workflow completion to user</action>
+<action>Report workflow completion to user with personalized message: "✅ Correct Course workflow complete, {user_name}!"</action>
 <action>Remind user of success criteria and next steps for implementation team</action>
 </step>
 

package/src/modules/bmm/workflows/4-implementation/correct-course/workflow.yaml

@@ -6,13 +6,19 @@ author: "BMad Method"
 config_source: "{project-root}/bmad/bmm/config.yaml"
 output_folder: "{config_source}:output_folder"
 user_name: "{config_source}:user_name"
+communication_language: "{config_source}:communication_language"
+user_skill_level: "{config_source}:user_skill_level"
+document_output_language: "{config_source}:document_output_language"
 date: system-generated
 
 installed_path: "{project-root}/bmad/bmm/workflows/4-implementation/correct-course"
 template: false
 instructions: "{installed_path}/instructions.md"
 validation: "{installed_path}/checklist.md"
+checklist: "{installed_path}/checklist.md"
+default_output_file: "{output_folder}/sprint-change-proposal-{date}.md"
 
+# Workflow execution mode (interactive: step-by-step with user, non-interactive: automated)
 mode: interactive
 
 required_inputs:
@@ -33,3 +39,7 @@ halt_conditions:
 execution_modes:
   - incremental: "Recommended - Refine each edit with user collaboration"
   - batch: "Present all changes at once for review"
+
+standalone: true
+
+web_bundle: false

package/src/modules/bmm/workflows/4-implementation/create-story/README.md

@@ -1,42 +1,129 @@
-# Create Story
+---
+last-redoc-date: 2025-10-01
+---
 
-## Purpose
+# Create Story Workflow
 
-Generate the next user story from epics/PRD and architecture context into your configured stories directory using a consistent structure.
+The create-story workflow is the entry point for v6's just-in-time story generation approach, run exclusively by the Scrum Master (SM) agent. Unlike batch processing methodologies, this workflow generates exactly ONE story at a time based on the current epic backlog state, ensuring stories are created only when needed and with the most current context. The SM analyzes the epic's progress, identifies what needs to be built next based on epics.md enumeration, and generates a complete story specification including acceptance criteria, technical approach, and implementation guidance pulled directly from tech specs, PRD, and architecture documentation.
 
-## Highlights
+This workflow represents a fundamental shift from traditional upfront planning to adaptive story generation. By creating stories one at a time and enforcing strict verification against epics.md, the SM ensures that only planned and approved stories are created. The workflow operates in non-interactive "#yolo" mode by default, minimizing prompts while maintaining quality through rigorous source document grounding. It will HALT if epics.md doesn't explicitly enumerate the next story, forcing proper planning through the correct-course workflow rather than allowing ad-hoc story creation.
 
-- Auto-detects next story id based on existing files
-- Pulls ACs from `epics.md` (or PRD) when available
-- Saves to `{dev_story_location}` from `bmad/bmm/config.yaml`
-- Optional: immediately runs Story Context workflow for the new story
-- Spec-compliant with core workflow engine at `bmad/core/tasks/workflow.md`
-- Defaults to non-interactive `#yolo` mode; only asks when strictly necessary
-- Safeguard: Will NOT create a new story unless epics.md explicitly enumerates it; otherwise halts and instructs to run PM/SM `*correct-course`
+The workflow's intelligent document discovery system automatically finds the relevant tech spec for the current epic (using pattern `tech-spec-epic-{epic_num}-*.md`), loads all architecture documents from both docs/ and output folders, and synthesizes requirements from multiple sources in priority order. After story creation, it can optionally trigger the story-context workflow to generate just-in-time technical expertise for the developer.
 
-## Invoke
+## Usage
 
-- By path: `workflow {project-root}/bmad/bmm/workflows/4-implementation/create-story/workflow.yaml`
+```bash
+# SM initiates story creation for the next piece of work
+bmad sm *create-story
+```
 
-## Variables
+The SM runs this workflow when:
 
-- `story_dir`: from config `dev_story_location`
-- `epics_file`: default `{output_folder}/epics.md`
-- `prd_file`: default `{output_folder}/prd.md`
-- `hla_file`: default `{output_folder}/high-level-architecture.md`
-- `auto_run_context`: default `true`
-- `tech_spec_file`: auto-discovered in `{project-root}/docs` with pattern `tech-spec-epic-<epic_num>-*.md` (latest by modified time)
-- `execution_mode`: `#yolo` by default to minimize prompts
-- `arch_docs_search_dirs`: `docs/` and `output_folder` are searched for architecture docs
-- `arch_docs_file_names`: includes `tech-stack.md`, `unified-project-structure.md`, `coding-standards.md`, `testing-strategy.md`, `backend-architecture.md`, `frontend-architecture.md`, `data-models.md`, `database-schema.md`, `rest-api-spec.md`, `external-apis.md`
+- The current sprint has capacity for new work
+- The previous story status is "Done" or "Approved"
+- The team is ready for the next planned story in the epic
+- Story preparation is needed before development
 
-## Output
+## Inputs
 
-- New story markdown: `{story_dir}/story-<epic_num>.<story_num>.md`
-- Status: `Draft`
-- Guardrail: If `epics.md` lacks the next story under the current epic, the workflow halts with: "No planned next story found in epics.md for epic <epic_num>. Please load either PM (Product Manager) agent at `{project-root}/bmad/bmm/agents/pm.md` or SM (Scrum Master) agent at `{project-root}/bmad/bmm/agents/sm.md` and run `*correct-course` to add/modify epic stories, then rerun create-story."
+**Required Context Files:**
 
-## After Creation
+- **epics.md**: MANDATORY - Must explicitly enumerate the next story or workflow halts
+- **tech-spec-epic-{N}-\*.md**: Epic-specific technical specification (auto-discovered)
+- **PRD.md**: Product requirements document (fallback for requirements)
+- **Architecture Documents**: Automatically discovered from docs/ and output folders:
+  - tech-stack.md, unified-project-structure.md, coding-standards.md
+  - testing-strategy.md, backend-architecture.md, frontend-architecture.md
+  - data-models.md, database-schema.md, rest-api-spec.md, external-apis.md
 
-- Approve the story when ready (Status → Approved)
-- Then run the Dev agent `*develop` command (uses the Dev Story workflow)
+**Workflow Variables:**
+
+- `story_dir`: From config `dev_story_location` - where stories are saved
+- `epic_num`: Current epic number (auto-detected from existing stories)
+- `story_num`: Next story number (incremented from last completed story)
+- `auto_run_context`: Default true - runs story-context workflow after creation
+- `non_interactive`: Default true - operates in "#yolo" mode with minimal prompts
+
+## Outputs
+
+**Primary Deliverable:**
+
+- **Story Document** (`{story_dir}/story-{epic_num}.{story_num}.md`): Complete story specification including:
+  - User story statement (role, action, benefit)
+  - Acceptance criteria extracted from tech spec or epics.md
+  - Tasks and subtasks mapped to ACs
+  - Testing requirements per testing strategy
+  - Dev notes with source citations
+  - Status: "Draft" (requires approval before development)
+
+**Validation Safeguards:**
+
+- **Epic Enumeration Check**: If epics.md doesn't list the next story, workflow HALTS with:
+  ```
+  "No planned next story found in epics.md for epic {epic_num}.
+  Please load either PM or SM agent and run *correct-course to add/modify epic stories."
+  ```
+- **Status Check**: Won't create new story if current story isn't Done/Approved
+- **Document Grounding**: All requirements traced to source documents (no invention)
+
+## Key Features
+
+**Strict Planning Enforcement**: The workflow will NOT create stories that aren't explicitly planned in epics.md. This prevents scope creep and ensures all work is properly approved through the planning process.
+
+**Intelligent Document Discovery**: Automatically finds the latest tech spec for the epic using glob patterns, discovers all architecture documents across multiple directories, and builds a prioritized document set for requirement extraction.
+
+**Source Document Grounding**: Every requirement, acceptance criterion, and technical constraint is traced to a specific source document. The workflow explicitly forbids inventing domain facts not present in source materials.
+
+**Non-Interactive by Default**: Operates in "#yolo" mode to minimize interruptions, only prompting when absolutely necessary (like missing critical configuration). This enables smooth automated story preparation.
+
+**Automatic Context Generation**: When `auto_run_context` is true (default), automatically triggers the story-context workflow to generate developer expertise injection for the newly created story.
+
+## Integration with v6 Flow
+
+The create-story workflow is step 1 in the v6 implementation cycle:
+
+1. **SM: create-story** ← You are here
+2. SM: story-context (adds JIT technical expertise)
+3. DEV: dev-story (implements with generated context)
+4. DEV/SR: code-review (validates completion)
+5. If needed: correct-course (adjusts direction)
+6. After epic: retrospective (captures learnings)
+
+This workflow establishes the "what" that needs to be built, strictly based on planned epics. The story-context workflow will later add the "how" through just-in-time technical expertise injection.
+
+## Document Priority Order
+
+The workflow uses this priority for extracting requirements:
+
+1. **tech_spec_file**: Epic-scoped technical specification (highest priority)
+2. **epics_file**: Acceptance criteria and story breakdown
+3. **prd_file**: Business requirements and constraints
+4. **Architecture docs**: Constraints, patterns, and technical guidance
+
+## Workflow Behavior
+
+**Story Number Management:**
+
+- Automatically detects next story number from existing files
+- Won't skip numbers or create duplicates
+- Maintains epic.story numbering convention
+
+**Update vs Create:**
+
+- If latest story status != Done/Approved: Updates existing story
+- If latest story status == Done/Approved: Creates next story (if enumerated in epics.md)
+
+**Epic Advancement:**
+
+- In non-interactive mode: Stays within current epic
+- Interactive mode: Can prompt for new epic number
+
+## Troubleshooting
+
+**"No planned next story found in epics.md"**: The next story isn't enumerated in epics.md. Run SM or PM agent's `*correct-course` to properly plan and add the story to the epic.
+
+**Missing story_dir Configuration**: Ensure `dev_story_location` is set in bmad/bmm/config.yaml
+
+**Tech Spec Not Found**: The workflow looks for `tech-spec-epic-{N}-*.md` pattern. Ensure tech specs follow this naming convention.
+
+**Architecture Documents Missing**: While not fatal, missing architecture docs reduce story context quality. Ensure key docs exist in docs/ or output folder.

package/src/modules/bmm/workflows/4-implementation/create-story/checklist.md

@@ -1,39 +1,240 @@
----
-title: 'Create Story Checklist'
-validation-target: 'Newly generated story markdown file'
-required-inputs:
-  - 'epics.md (preferred) or PRD'
-optional-inputs:
-  - 'HLA document for architecture context'
-validation-rules:
-  - 'Story structure matches sections: Status, Story, Acceptance Criteria, Tasks/Subtasks, Dev Notes, Change Log, Dev Agent Record'
-  - 'Dev Notes include Project Structure Notes and References subsections'
-  - 'All non-trivial technical notes include a source citation'
-  - 'Tasks include explicit testing subtasks based on testing strategy'
----
-
-# Create Story Checklist
-
-## Document Structure
-
-- [ ] Title includes story id and title
-- [ ] Status set to Draft
-- [ ] Story section present with As a / I want / so that
-- [ ] Acceptance Criteria is a numbered list
-- [ ] Tasks/Subtasks present with checkboxes
-- [ ] Dev Notes includes architecture/testing context
-- [ ] Change Log table initialized
-- [ ] Dev Agent Record sections present (Context Reference, Agent Model Used, Debug Log References, Completion Notes, File List)
-
-## Content Quality
-
-- [ ] Acceptance Criteria sourced from epics/PRD (or explicitly confirmed by user)
-- [ ] Tasks reference AC numbers where applicable
-- [ ] Dev Notes do not invent details; cite sources where possible
-- [ ] File saved to stories directory from config (dev_story_location)
-- [ ] If creating a new story number, epics.md explicitly enumerates this story under the target epic; otherwise generation HALTED with instruction to run PM/SM `*correct-course` (open `{project-root}/bmad/bmm/agents/pm.md` or `{project-root}/bmad/bmm/agents/sm.md` and execute `*correct-course`)
-
-## Optional Post-Generation
-
-- [ ] Story Context generation run (if auto_run_context)
-- [ ] Context Reference recorded in story
+# Create Story Quality Validation Checklist
+
+```xml
+<critical>This validation runs in a FRESH CONTEXT by an independent validator agent</critical>
+<critical>The validator audits story quality and offers to improve if issues are found</critical>
+<critical>Load only the story file and necessary source documents - do NOT load workflow instructions</critical>
+
+<validation-checklist>
+
+<expectations>
+**What create-story workflow should have accomplished:**
+
+1. **Previous Story Continuity:** If a previous story exists (status: done/review/in-progress), current story should have "Learnings from Previous Story" subsection in Dev Notes that references: new files created, completion notes, architectural decisions, unresolved review items
+2. **Source Document Coverage:** Story should cite tech spec (if exists), epics, PRD, and relevant architecture docs (architecture.md, testing-strategy.md, coding-standards.md, unified-project-structure.md)
+3. **Requirements Traceability:** ACs sourced from tech spec (preferred) or epics, not invented
+4. **Dev Notes Quality:** Specific guidance with citations, not generic advice
+5. **Task-AC Mapping:** Every AC has tasks, every task references AC, testing subtasks present
+6. **Structure:** Status="drafted", proper story statement, Dev Agent Record sections initialized
+</expectations>
+
+## Validation Steps
+
+### 1. Load Story and Extract Metadata
+- [ ] Load story file: {{story_file_path}}
+- [ ] Parse sections: Status, Story, ACs, Tasks, Dev Notes, Dev Agent Record, Change Log
+- [ ] Extract: epic_num, story_num, story_key, story_title
+- [ ] Initialize issue tracker (Critical/Major/Minor)
+
+### 2. Previous Story Continuity Check
+
+**Find previous story:**
+- [ ] Load {output_folder}/sprint-status.yaml
+- [ ] Find current {{story_key}} in development_status
+- [ ] Identify story entry immediately above (previous story)
+- [ ] Check previous story status
+
+**If previous story status is done/review/in-progress:**
+- [ ] Load previous story file: {story_dir}/{{previous_story_key}}.md
+- [ ] Extract: Dev Agent Record (Completion Notes, File List with NEW/MODIFIED)
+- [ ] Extract: Senior Developer Review section if present
+- [ ] Count unchecked [ ] items in Review Action Items
+- [ ] Count unchecked [ ] items in Review Follow-ups (AI)
+
+**Validate current story captured continuity:**
+- [ ] Check: "Learnings from Previous Story" subsection exists in Dev Notes
+  - If MISSING and previous story has content → **CRITICAL ISSUE**
+- [ ] If subsection exists, verify it includes:
+  - [ ] References to NEW files from previous story → If missing → **MAJOR ISSUE**
+  - [ ] Mentions completion notes/warnings → If missing → **MAJOR ISSUE**
+  - [ ] Calls out unresolved review items (if any exist) → If missing → **CRITICAL ISSUE**
+  - [ ] Cites previous story: [Source: stories/{{previous_story_key}}.md]
+
+**If previous story status is backlog/drafted:**
+- [ ] No continuity expected (note this)
+
+**If no previous story exists:**
+- [ ] First story in epic, no continuity expected
+
+### 3. Source Document Coverage Check
+
+**Build available docs list:**
+- [ ] Check exists: tech-spec-epic-{{epic_num}}*.md in {tech_spec_search_dir}
+- [ ] Check exists: {output_folder}/epics.md
+- [ ] Check exists: {output_folder}/PRD.md
+- [ ] Check exists in {output_folder}/ or {project-root}/docs/:
+  - architecture.md, testing-strategy.md, coding-standards.md
+  - unified-project-structure.md, tech-stack.md
+  - backend-architecture.md, frontend-architecture.md, data-models.md
+
+**Validate story references available docs:**
+- [ ] Extract all [Source: ...] citations from story Dev Notes
+- [ ] Tech spec exists but not cited → **CRITICAL ISSUE**
+- [ ] Epics exists but not cited → **CRITICAL ISSUE**
+- [ ] Architecture.md exists → Read for relevance → If relevant but not cited → **MAJOR ISSUE**
+- [ ] Testing-strategy.md exists → Check Dev Notes mentions testing standards → If not → **MAJOR ISSUE**
+- [ ] Testing-strategy.md exists → Check Tasks have testing subtasks → If not → **MAJOR ISSUE**
+- [ ] Coding-standards.md exists → Check Dev Notes references standards → If not → **MAJOR ISSUE**
+- [ ] Unified-project-structure.md exists → Check Dev Notes has "Project Structure Notes" subsection → If not → **MAJOR ISSUE**
+
+**Validate citation quality:**
+- [ ] Verify cited file paths are correct and files exist → Bad citations → **MAJOR ISSUE**
+- [ ] Check citations include section names, not just file paths → Vague citations → **MINOR ISSUE**
+
+### 4. Acceptance Criteria Quality Check
+
+- [ ] Extract Acceptance Criteria from story
+- [ ] Count ACs: {{ac_count}} (if 0 → **CRITICAL ISSUE** and halt)
+- [ ] Check story indicates AC source (tech spec, epics, PRD)
+
+**If tech spec exists:**
+- [ ] Load tech spec
+- [ ] Search for this story number
+- [ ] Extract tech spec ACs for this story
+- [ ] Compare story ACs vs tech spec ACs → If mismatch → **MAJOR ISSUE**
+
+**If no tech spec but epics.md exists:**
+- [ ] Load epics.md
+- [ ] Search for Epic {{epic_num}}, Story {{story_num}}
+- [ ] Story not found in epics → **CRITICAL ISSUE** (should have halted)
+- [ ] Extract epics ACs
+- [ ] Compare story ACs vs epics ACs → If mismatch without justification → **MAJOR ISSUE**
+
+**Validate AC quality:**
+- [ ] Each AC is testable (measurable outcome)
+- [ ] Each AC is specific (not vague)
+- [ ] Each AC is atomic (single concern)
+- [ ] Vague ACs found → **MINOR ISSUE**
+
+### 5. Task-AC Mapping Check
+
+- [ ] Extract Tasks/Subtasks from story
+- [ ] For each AC: Search tasks for "(AC: #{{ac_num}})" reference
+  - [ ] AC has no tasks → **MAJOR ISSUE**
+- [ ] For each task: Check if references an AC number
+  - [ ] Tasks without AC refs (and not testing/setup) → **MINOR ISSUE**
+- [ ] Count tasks with testing subtasks
+  - [ ] Testing subtasks < ac_count → **MAJOR ISSUE**
+
+### 6. Dev Notes Quality Check
+
+**Check required subsections exist:**
+- [ ] Architecture patterns and constraints
+- [ ] References (with citations)
+- [ ] Project Structure Notes (if unified-project-structure.md exists)
+- [ ] Learnings from Previous Story (if previous story has content)
+- [ ] Missing required subsections → **MAJOR ISSUE**
+
+**Validate content quality:**
+- [ ] Architecture guidance is specific (not generic "follow architecture docs") → If generic → **MAJOR ISSUE**
+- [ ] Count citations in References subsection
+  - [ ] No citations → **MAJOR ISSUE**
+  - [ ] < 3 citations and multiple arch docs exist → **MINOR ISSUE**
+- [ ] Scan for suspicious specifics without citations:
+  - API endpoints, schema details, business rules, tech choices
+  - [ ] Likely invented details found → **MAJOR ISSUE**
+
+### 7. Story Structure Check
+
+- [ ] Status = "drafted" → If not → **MAJOR ISSUE**
+- [ ] Story section has "As a / I want / so that" format → If malformed → **MAJOR ISSUE**
+- [ ] Dev Agent Record has required sections:
+  - Context Reference, Agent Model Used, Debug Log References, Completion Notes List, File List
+  - [ ] Missing sections → **MAJOR ISSUE**
+- [ ] Change Log initialized → If missing → **MINOR ISSUE**
+- [ ] File in correct location: {story_dir}/{{story_key}}.md → If not → **MAJOR ISSUE**
+
+### 8. Unresolved Review Items Alert
+
+**CRITICAL CHECK for incomplete review items from previous story:**
+
+- [ ] If previous story has "Senior Developer Review (AI)" section:
+  - [ ] Count unchecked [ ] items in "Action Items"
+  - [ ] Count unchecked [ ] items in "Review Follow-ups (AI)"
+  - [ ] If unchecked items > 0:
+    - [ ] Check current story "Learnings from Previous Story" mentions these
+    - [ ] If NOT mentioned → **CRITICAL ISSUE** with details:
+      - List all unchecked items with severity
+      - Note: "These may represent epic-wide concerns"
+      - Required: Add to Learnings section with note about pending items
+
+## Validation Report Generation
+
+**Calculate severity counts:**
+- Critical: {{critical_count}}
+- Major: {{major_count}}
+- Minor: {{minor_count}}
+
+**Determine outcome:**
+- Critical > 0 OR Major > 3 → **FAIL**
+- Major ≤ 3 and Critical = 0 → **PASS with issues**
+- All = 0 → **PASS**
+
+**Generate report:**
+```
+
+# Story Quality Validation Report
+
+Story: {{story_key}} - {{story_title}}
+Outcome: {{outcome}} (Critical: {{critical_count}}, Major: {{major_count}}, Minor: {{minor_count}})
+
+## Critical Issues (Blockers)
+
+{{list_each_with_description_and_evidence}}
+
+## Major Issues (Should Fix)
+
+{{list_each_with_description_and_evidence}}
+
+## Minor Issues (Nice to Have)
+
+{{list_each_with_description}}
+
+## Successes
+
+{{list_what_was_done_well}}
+
+```
+
+## User Alert and Remediation
+
+**If FAIL:**
+- Show issues summary and top 3 issues
+- Offer options: (1) Auto-improve story, (2) Show detailed findings, (3) Fix manually, (4) Accept as-is
+- If option 1: Re-load source docs, regenerate affected sections, re-run validation
+
+**If PASS with issues:**
+- Show issues list
+- Ask: "Improve story? (y/n)"
+- If yes: Enhance story with missing items
+
+**If PASS:**
+- Confirm: All quality standards met
+- List successes
+- Ready for story-context generation
+
+</validation-checklist>
+```
+
+## Quick Reference
+
+**Validation runs in fresh context and checks:**
+
+1. ✅ Previous story continuity captured (files, notes, **unresolved review items**)
+2. ✅ All relevant source docs discovered and cited
+3. ✅ ACs match tech spec/epics exactly
+4. ✅ Tasks cover all ACs with testing
+5. ✅ Dev Notes have specific guidance with citations (not generic)
+6. ✅ Structure and metadata complete
+
+**Severity Levels:**
+
+- **CRITICAL** = Missing previous story reference, missing tech spec cite, unresolved review items not called out, story not in epics
+- **MAJOR** = Missing arch docs, missing files from previous story, vague Dev Notes, ACs don't match source, no testing subtasks
+- **MINOR** = Vague citations, orphan tasks, missing Change Log
+
+**Outcome Triggers:**
+
+- **FAIL** = Any critical OR >3 major issues
+- **PASS with issues** = ≤3 major issues, no critical
+- **PASS** = All checks passed