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

package/src/modules/bmm/workflows/4-implementation/code-review/workflow.yaml

@@ -0,0 +1,61 @@
+# Review Story Workflow
+name: code-review
+description: "Perform a Senior Developer code review on a completed story flagged Ready for Review, leveraging story-context, epic tech-spec, repo docs, MCP servers for latest best-practices, and web search as fallback. Appends structured review notes to the story."
+author: "BMad"
+
+# Critical variables from config
+config_source: "{project-root}/{bmad_folder}/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
+sprint_artifacts: "{config_source}:sprint_artifacts"
+sprint_status: "{sprint_artifacts}/sprint-status.yaml || {output_folder}/sprint-status.yaml"
+
+# Workflow components
+installed_path: "{project-root}/{bmad_folder}/bmm/workflows/4-implementation/code-review"
+instructions: "{installed_path}/instructions.md"
+validation: "{installed_path}/checklist.md"
+template: false
+
+variables:
+  story_dir: "{sprint_artifacts}"
+  tech_spec_search_dir: "{output_folder}"
+  tech_spec_glob_template: "tech-spec-epic-{{epic_num}}*.md"
+  arch_docs_search_dirs: |
+    - "{output_folder}"
+  arch_docs_file_names: |
+    - architecture.md
+  backlog_file: "{output_folder}/backlog.md"
+  update_epic_followups: true
+  epic_followups_section_title: "Post-Review Follow-ups"
+
+# Smart input file references - handles both whole docs and sharded docs
+# Priority: Whole document first, then sharded version
+# Strategy: SELECTIVE LOAD - only load the specific epic needed for this story review
+input_file_patterns:
+  architecture:
+    description: "System architecture for review context"
+    whole: "{output_folder}/*architecture*.md"
+    sharded: "{output_folder}/*architecture*/*.md"
+    load_strategy: "FULL_LOAD"
+  ux_design:
+    description: "UX design specification (if UI review)"
+    whole: "{output_folder}/*ux*.md"
+    sharded: "{output_folder}/*ux*/*.md"
+    load_strategy: "FULL_LOAD"
+  epics:
+    description: "Epic containing story being reviewed"
+    whole: "{output_folder}/*epic*.md"
+    sharded_index: "{output_folder}/*epic*/index.md"
+    sharded_single: "{output_folder}/*epic*/epic-{{epic_num}}.md"
+    load_strategy: "SELECTIVE_LOAD"
+  document_project:
+    description: "Brownfield project documentation (optional)"
+    sharded: "{output_folder}/index.md"
+    load_strategy: "INDEX_GUIDED"
+
+standalone: true
+web_bundle: false

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

@@ -1,6 +1,6 @@
 # Change Navigation Checklist
 
-<critical>This checklist is executed as part of: {project-root}/bmad/bmm/workflows/4-implementation/correct-course/workflow.yaml</critical>
+<critical>This checklist is executed as part of: {project-root}/{bmad_folder}/bmm/workflows/4-implementation/correct-course/workflow.yaml</critical>
 <critical>Work through each section systematically with the user, recording findings and impacts</critical>
 
 <checklist>
@@ -33,8 +33,8 @@
 </check-item>
 
 <halt-condition>
-<check>If trigger is unclear: "Cannot proceed without understanding what caused the need for change"</check>
-<check>If no evidence provided: "Need concrete evidence or examples of the issue before analyzing impact"</check>
+<action if="trigger is unclear">HALT: "Cannot proceed without understanding what caused the need for change"</action>
+<action if="no evidence provided">HALT: "Need concrete evidence or examples of the issue before analyzing impact"</action>
 </halt-condition>
 
 </section>
@@ -261,9 +261,9 @@
 </check-item>
 
 <halt-condition>
-<check>If any critical section cannot be completed: "Cannot proceed to proposal without complete impact analysis"</check>
-<check>If user approval not obtained: "Must have explicit approval before implementing changes"</check>
-<check>If handoff responsibilities unclear: "Must clearly define who will execute the proposed changes"</check>
+<action if="any critical section cannot be completed">HALT: "Cannot proceed to proposal without complete impact analysis"</action>
+<action if="user approval not obtained">HALT: "Must have explicit approval before implementing changes"</action>
+<action if="handoff responsibilities unclear">HALT: "Must clearly define who will execute the proposed changes"</action>
 </halt-condition>
 
 </section>

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

@@ -1,42 +1,48 @@
 # Correct Course - Sprint Change Management Instructions
 
-<critical>The workflow execution engine is governed by: {project-root}/bmad/core/tasks/workflow.md</critical>
-<critical>You MUST have already loaded and processed: {project-root}/bmad/bmm/workflows/4-implementation/correct-course/workflow.yaml</critical>
+<critical>The workflow execution engine is governed by: {project-root}/{bmad_folder}/core/tasks/workflow.xml</critical>
+<critical>You MUST have already loaded and processed: {project-root}/{bmad_folder}/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="0.5" goal="Discover and load project documents">
+  <invoke-protocol name="discover_inputs" />
+  <note>After discovery, these content variables are available: {prd_content}, {epics_content}, {architecture_content}, {ux_design_content}, {tech_spec_content}, {document_project_content}</note>
 </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 +87,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 +138,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 +146,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>If yes:</check>
-<action>Finalize Sprint Change Proposal document</action>
-<action>Determine change scope classification:</action>
+</check>
+
+<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 +164,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="Minor scope">
+  <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="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:</check>
-<action>Route to: Product Manager / Solution Architect</action>
-<action>Deliverables: Complete Sprint Change Proposal + escalation notice</action>
+<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 +199,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

@@ -3,33 +3,56 @@ name: "correct-course"
 description: "Navigate significant changes during sprint execution by analyzing impact, proposing solutions, and routing for implementation"
 author: "BMad Method"
 
-config_source: "{project-root}/bmad/bmm/config.yaml"
+config_source: "{project-root}/{bmad_folder}/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
+sprint_artifacts: "{config_source}:sprint_artifacts"
+sprint_status: "{sprint_artifacts}/sprint-status.yaml || {output_folder}/sprint-status.yaml"
 
-installed_path: "{project-root}/bmad/bmm/workflows/4-implementation/correct-course"
+# Smart input file references - handles both whole docs and sharded docs
+# Priority: Whole document first, then sharded version
+# Strategy: Load project context for impact analysis
+input_file_patterns:
+  prd:
+    description: "Product requirements for impact analysis"
+    whole: "{output_folder}/*prd*.md"
+    sharded: "{output_folder}/*prd*/*.md"
+    load_strategy: "FULL_LOAD"
+  epics:
+    description: "All epics to analyze change impact"
+    whole: "{output_folder}/*epic*.md"
+    sharded: "{output_folder}/*epic*/*.md"
+    load_strategy: "FULL_LOAD"
+  architecture:
+    description: "System architecture and decisions"
+    whole: "{output_folder}/*architecture*.md"
+    sharded: "{output_folder}/*architecture*/*.md"
+    load_strategy: "FULL_LOAD"
+  ux_design:
+    description: "UX design specification (if UI impacts)"
+    whole: "{output_folder}/*ux*.md"
+    sharded: "{output_folder}/*ux*/*.md"
+    load_strategy: "FULL_LOAD"
+  tech_spec:
+    description: "Technical specification"
+    whole: "{output_folder}/tech-spec*.md"
+    load_strategy: "FULL_LOAD"
+  document_project:
+    description: "Brownfield project documentation (optional)"
+    sharded: "{output_folder}/index.md"
+    load_strategy: "INDEX_GUIDED"
+
+installed_path: "{project-root}/{bmad_folder}/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"
 
-mode: interactive
-
-required_inputs:
-  - change_trigger: "Description of the issue or change that triggered this workflow"
-  - project_documents: "Access to PRD, Epics/Stories, Architecture, UI/UX specs"
-
-output_artifacts:
-  - sprint_change_proposal: "Comprehensive proposal documenting issue, impact, and recommended changes"
-  - artifact_edits: "Specific before/after edits for affected documents"
-  - handoff_plan: "Clear routing for implementation based on change scope"
-
-halt_conditions:
-  - "Change trigger unclear or undefined"
-  - "Core project documents unavailable"
-  - "Impact analysis incomplete"
-  - "User approval not obtained"
+standalone: true
 
-execution_modes:
-  - incremental: "Recommended - Refine each edit with user collaboration"
-  - batch: "Present all changes at once for review"
+web_bundle: false

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