bmad-method 6.0.0-alpha.17 → 6.0.0-alpha.18

package/src/modules/bmgd/workflows/4-production/create-story/checklist.md

@@ -1,240 +1,358 @@
-# 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 Context Quality Competition Prompt
+
+## **🔥 CRITICAL MISSION: Outperform and Fix the Original Create-Story LLM**
+
+You are an independent quality validator in a **FRESH CONTEXT**. Your mission is to **thoroughly review** a story file that was generated by the create-story workflow and **systematically identify any mistakes, omissions, or disasters** that the original LLM missed.
+
+**Your purpose is NOT just to validate - it's to FIX and PREVENT LLM developer mistakes, omissions, or disasters!**
+
+### **🚨 CRITICAL MISTAKES TO PREVENT:**
+
+- **Reinventing wheels** - Creating duplicate functionality instead of reusing existing
+- **Wrong libraries** - Using incorrect frameworks, versions, or dependencies
+- **Wrong file locations** - Violating project structure and organization
+- **Breaking regressions** - Implementing changes that break existing functionality
+- **Ignoring UX** - Not following user experience design requirements
+- **Vague implementations** - Creating unclear, ambiguous implementations
+- **Lying about completion** - Implementing incorrectly or incompletely
+- **Not learning from past work** - Ignoring previous story learnings and patterns
+
+### **🚨 EXHAUSTIVE ANALYSIS REQUIRED:**
+
+You must thoroughly analyze **ALL artifacts** to extract critical context - do NOT be lazy or skim! This is the most important quality control function in the entire development process!
+
+### **🔬 UTILIZE SUBPROCESSES AND SUBAGENTS:**
+
+Use research subagents, subprocesses, or parallel processing if available to thoroughly analyze different artifacts **simultaneously and thoroughly**. Leave no stone unturned!
+
+### **🎯 COMPETITIVE EXCELLENCE:**
+
+This is a COMPETITION to create the **ULTIMATE story context** that makes LLM developer mistakes **IMPOSSIBLE**!
+
+## **🚀 HOW TO USE THIS CHECKLIST**
+
+### **When Running from Create-Story Workflow:**
+
+- The `{project_root}/_bmad/core/tasks/validate-workflow.xml` framework will automatically:
+  - Load this checklist file
+  - Load the newly created story file (`{story_file_path}`)
+  - Load workflow variables from `{installed_path}/workflow.yaml`
+  - Execute the validation process
+
+### **When Running in Fresh Context:**
+
+- User should provide the story file path being reviewed
+- Load the story file directly
+- Load the corresponding workflow.yaml for variable context
+- Proceed with systematic analysis
+
+### **Required Inputs:**
+
+- **Story file**: The story file to review and improve
+- **Workflow variables**: From workflow.yaml (story_dir, output_folder, epics_file, etc.)
+- **Source documents**: Epics, architecture, etc. (discovered or provided)
+- **Validation framework**: `validate-workflow.xml` (handles checklist execution)
+
+---
+
+## **🔬 SYSTEMATIC RE-ANALYSIS APPROACH**
+
+You will systematically re-do the entire story creation process, but with a critical eye for what the original LLM might have missed:
+
+### **Step 1: Load and Understand the Target**
+
+1. **Load the workflow configuration**: `{installed_path}/workflow.yaml` for variable inclusion
+2. **Load the story file**: `{story_file_path}` (provided by user or discovered)
+3. **Load validation framework**: `{project_root}/_bmad/core/tasks/validate-workflow.xml`
+4. **Extract metadata**: epic_num, story_num, story_key, story_title from story file
+5. **Resolve all workflow variables**: story_dir, output_folder, epics_file, architecture_file, etc.
+6. **Understand current status**: What story implementation guidance is currently provided?
+
+**Note:** If running in fresh context, user should provide the story file path being reviewed. If running from create-story workflow, the validation framework will automatically discover the checklist and story file.
+
+### **Step 2: Exhaustive Source Document Analysis**
+
+**🔥 CRITICAL: Treat this like YOU are creating the story from scratch to PREVENT DISASTERS!**
+**Discover everything the original LLM missed that could cause developer mistakes, omissions, or disasters!**
+
+#### **2.1 Epics and Stories Analysis**
+
+- Load `{epics_file}` (or sharded equivalents)
+- Extract **COMPLETE Epic {{epic_num}} context**:
+  - Epic objectives and business value
+  - ALL stories in this epic (for cross-story context)
+  - Our specific story's requirements, acceptance criteria
+  - Technical requirements and constraints
+  - Cross-story dependencies and prerequisites
+
+#### **2.2 Architecture Deep-Dive**
+
+- Load `{architecture_file}` (single or sharded)
+- **Systematically scan for ANYTHING relevant to this story:**
+  - Technical stack with versions (languages, frameworks, libraries)
+  - Code structure and organization patterns
+  - API design patterns and contracts
+  - Database schemas and relationships
+  - Security requirements and patterns
+  - Performance requirements and optimization strategies
+  - Testing standards and frameworks
+  - Deployment and environment patterns
+  - Integration patterns and external services
+
+#### **2.3 Previous Story Intelligence (if applicable)**
+
+- If `story_num > 1`, load the previous story file
+- Extract **actionable intelligence**:
+  - Dev notes and learnings
+  - Review feedback and corrections needed
+  - Files created/modified and their patterns
+  - Testing approaches that worked/didn't work
+  - Problems encountered and solutions found
+  - Code patterns and conventions established
+
+#### **2.4 Git History Analysis (if available)**
+
+- Analyze recent commits for patterns:
+  - Files created/modified in previous work
+  - Code patterns and conventions used
+  - Library dependencies added/changed
+  - Architecture decisions implemented
+  - Testing approaches used
+
+#### **2.5 Latest Technical Research**
+
+- Identify any libraries/frameworks mentioned
+- Research latest versions and critical information:
+  - Breaking changes or security updates
+  - Performance improvements or deprecations
+  - Best practices for current versions
+
+### **Step 3: Disaster Prevention Gap Analysis**
+
+**🚨 CRITICAL: Identify every mistake the original LLM missed that could cause DISASTERS!**
+
+#### **3.1 Reinvention Prevention Gaps**
+
+- **Wheel reinvention:** Areas where developer might create duplicate functionality
+- **Code reuse opportunities** not identified that could prevent redundant work
+- **Existing solutions** not mentioned that developer should extend instead of replace
+
+#### **3.2 Technical Specification DISASTERS**
+
+- **Wrong libraries/frameworks:** Missing version requirements that could cause compatibility issues
+- **API contract violations:** Missing endpoint specifications that could break integrations
+- **Database schema conflicts:** Missing requirements that could corrupt data
+- **Security vulnerabilities:** Missing security requirements that could expose the system
+- **Performance disasters:** Missing requirements that could cause system failures
+
+#### **3.3 File Structure DISASTERS**
+
+- **Wrong file locations:** Missing organization requirements that could break build processes
+- **Coding standard violations:** Missing conventions that could create inconsistent codebase
+- **Integration pattern breaks:** Missing data flow requirements that could cause system failures
+- **Deployment failures:** Missing environment requirements that could prevent deployment
+
+#### **3.4 Regression DISASTERS**
+
+- **Breaking changes:** Missing requirements that could break existing functionality
+- **Test failures:** Missing test requirements that could allow bugs to reach production
+- **UX violations:** Missing user experience requirements that could ruin the product
+- **Learning failures:** Missing previous story context that could repeat same mistakes
+
+#### **3.5 Implementation DISASTERS**
+
+- **Vague implementations:** Missing details that could lead to incorrect or incomplete work
+- **Completion lies:** Missing acceptance criteria that could allow fake implementations
+- **Scope creep:** Missing boundaries that could cause unnecessary work
+- **Quality failures:** Missing quality requirements that could deliver broken features
+
+### **Step 4: LLM-Dev-Agent Optimization Analysis**
+
+**CRITICAL STEP: Optimize story context for LLM developer agent consumption**
+
+**Analyze current story for LLM optimization issues:**
+
+- **Verbosity problems:** Excessive detail that wastes tokens without adding value
+- **Ambiguity issues:** Vague instructions that could lead to multiple interpretations
+- **Context overload:** Too much information not directly relevant to implementation
+- **Missing critical signals:** Key requirements buried in verbose text
+- **Poor structure:** Information not organized for efficient LLM processing
+
+**Apply LLM Optimization Principles:**
+
+- **Clarity over verbosity:** Be precise and direct, eliminate fluff
+- **Actionable instructions:** Every sentence should guide implementation
+- **Scannable structure:** Use clear headings, bullet points, and emphasis
+- **Token efficiency:** Pack maximum information into minimum text
+- **Unambiguous language:** Clear requirements with no room for interpretation
+
+### **Step 5: Improvement Recommendations**
+
+**For each gap identified, provide specific, actionable improvements:**
+
+#### **5.1 Critical Misses (Must Fix)**
+
+- Missing essential technical requirements
+- Missing previous story context that could cause errors
+- Missing anti-pattern prevention that could lead to duplicate code
+- Missing security or performance requirements
+
+#### **5.2 Enhancement Opportunities (Should Add)**
+
+- Additional architectural guidance that would help developer
+- More detailed technical specifications
+- Better code reuse opportunities
+- Enhanced testing guidance
+
+#### **5.3 Optimization Suggestions (Nice to Have)**
+
+- Performance optimization hints
+- Additional context for complex scenarios
+- Enhanced debugging or development tips
+
+#### **5.4 LLM Optimization Improvements**
+
+- Token-efficient phrasing of existing content
+- Clearer structure for LLM processing
+- More actionable and direct instructions
+- Reduced verbosity while maintaining completeness
+
+---
+
+## **🎯 COMPETITION SUCCESS METRICS**
+
+**You WIN against the original LLM if you identify:**
+
+### **Category 1: Critical Misses (Blockers)**
+
+- Essential technical requirements the developer needs but aren't provided
+- Previous story learnings that would prevent errors if ignored
+- Anti-pattern prevention that would prevent code duplication
+- Security or performance requirements that must be followed
+
+### **Category 2: Enhancement Opportunities**
+
+- Architecture guidance that would significantly help implementation
+- Technical specifications that would prevent wrong approaches
+- Code reuse opportunities the developer should know about
+- Testing guidance that would improve quality
+
+### **Category 3: Optimization Insights**
+
+- Performance or efficiency improvements
+- Development workflow optimizations
+- Additional context for complex scenarios
+
+---
+
+## **📋 INTERACTIVE IMPROVEMENT PROCESS**
+
+After completing your systematic analysis, present your findings to the user interactively:
+
+### **Step 5: Present Improvement Suggestions**
+
 ```
+🎯 **STORY CONTEXT QUALITY REVIEW COMPLETE**
+
+**Story:** {{story_key}} - {{story_title}}
 
-# Story Quality Validation Report
+I found {{critical_count}} critical issues, {{enhancement_count}} enhancements, and {{optimization_count}} optimizations.
 
-Story: {{story_key}} - {{story_title}}
-Outcome: {{outcome}} (Critical: {{critical_count}}, Major: {{major_count}}, Minor: {{minor_count}})
+## **🚨 CRITICAL ISSUES (Must Fix)**
 
-## Critical Issues (Blockers)
+{{list each critical issue with clear, actionable description}}
 
-{{list_each_with_description_and_evidence}}
+## **⚡ ENHANCEMENT OPPORTUNITIES (Should Add)**
 
-## Major Issues (Should Fix)
+{{list each enhancement with clear benefit description}}
 
-{{list_each_with_description_and_evidence}}
+## **✨ OPTIMIZATIONS (Nice to Have)**
 
-## Minor Issues (Nice to Have)
+{{list each optimization with benefit description}}
 
-{{list_each_with_description}}
+## **🤖 LLM OPTIMIZATION (Token Efficiency & Clarity)**
 
-## Successes
+{{list each LLM optimization that will improve dev agent performance:
+- Reduce verbosity while maintaining completeness
+- Improve structure for better LLM processing
+- Make instructions more actionable and direct
+- Enhance clarity and reduce ambiguity}}
+```
+
+### **Step 6: Interactive User Selection**
 
-{{list_what_was_done_well}}
+After presenting the suggestions, ask the user:
 
 ```
+**IMPROVEMENT OPTIONS:**
 
-## User Alert and Remediation
+Which improvements would you like me to apply to the story?
 
-**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
+**Select from the numbered list above, or choose:**
+- **all** - Apply all suggested improvements
+- **critical** - Apply only critical issues
+- **select** - I'll choose specific numbers
+- **none** - Keep story as-is
+- **details** - Show me more details about any suggestion
 
-**If PASS with issues:**
-- Show issues list
-- Ask: "Improve story? (y/n)"
-- If yes: Enhance story with missing items
+Your choice:
+```
 
-**If PASS:**
-- Confirm: All quality standards met
-- List successes
-- Ready for story-context generation
+### **Step 7: Apply Selected Improvements**
+
+When user accepts improvements:
+
+- **Load the story file**
+- **Apply accepted changes** (make them look natural, as if they were always there)
+- **DO NOT reference** the review process, original LLM, or that changes were "added" or "enhanced"
+- **Ensure clean, coherent final story** that reads as if it was created perfectly the first time
+
+### **Step 8: Confirmation**
+
+After applying changes:
 
-</validation-checklist>
 ```
+✅ **STORY IMPROVEMENTS APPLIED**
+
+Updated {{count}} sections in the story file.
+
+The story now includes comprehensive developer guidance to prevent common implementation issues and ensure flawless execution.
+
+**Next Steps:**
+1. Review the updated story
+2. Run `dev-story` for implementation
+```
+
+---
+
+## **💪 COMPETITIVE EXCELLENCE MINDSET**
+
+**Your goal:** Improve the story file with dev agent needed context that makes flawless implementation inevitable while being optimized for LLM developer agent consumption. Remember the dev agent will ONLY have this file to use.
 
-## Quick Reference
+**Success Criteria:** The LLM developer agent that processes your improved story will have:
 
-**Validation runs in fresh context and checks:**
+- ✅ Clear technical requirements they must follow
+- ✅ Previous work context they can build upon
+- ✅ Anti-pattern prevention to avoid common mistakes
+- ✅ Comprehensive guidance for efficient implementation
+- ✅ **Optimized content structure** for maximum clarity and minimum token waste
+- ✅ **Actionable instructions** with no ambiguity or verbosity
+- ✅ **Efficient information density** - maximum guidance in minimum text
 
-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
+**Every improvement should make it IMPOSSIBLE for the developer to:**
 
-**Severity Levels:**
+- Reinvent existing solutions
+- Use wrong approaches or libraries
+- Create duplicate functionality
+- Miss critical requirements
+- Make implementation errors
 
-- **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
+**LLM Optimization Should Make it IMPOSSIBLE for the developer agent to:**
 
-**Outcome Triggers:**
+- Misinterpret requirements due to ambiguity
+- Waste tokens on verbose, non-actionable content
+- Struggle to find critical information buried in text
+- Get confused by poor structure or organization
+- Miss key implementation signals due to inefficient communication
 
-- **FAIL** = Any critical OR >3 major issues
-- **PASS with issues** = ≤3 major issues, no critical
-- **PASS** = All checks passed
+**Go create the ultimate developer implementation guide! 🚀**