bmad-template/.codebuddy/skills/bmad-create-story/checklist.md

# 🎯 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 workflow framework will automatically:
  - Load this checklist file
  - Load the newly created story file (`{story_file_path}`)
  - Load workflow variables from `./workflow.md`
  - 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.md for variable context
- Proceed with systematic analysis

### **Required Inputs:**

- **Story file**: The story file to review and improve
- **Workflow variables**: From workflow.md (implementation_artifacts, epics_file, etc.)
- **Source documents**: Epics, architecture, etc. (discovered or provided)
- **Validation framework**: The workflow's checklist execution system

---

## **🔬 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**: `./workflow.md` for variable inclusion
2. **Load the story file**: `{story_file_path}` (provided by user or discovered)
3. **Extract metadata**: epic_num, story_num, story_key, story_title from story file
4. **Resolve all workflow variables**: implementation_artifacts, epics_file, architecture_file, etc.
5. **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}}

I found {{critical_count}} critical issues, {{enhancement_count}} enhancements, and {{optimization_count}} optimizations.

## **🚨 CRITICAL ISSUES (Must Fix)**

{{list each critical issue with clear, actionable description}}

## **⚡ ENHANCEMENT OPPORTUNITIES (Should Add)**

{{list each enhancement with clear benefit description}}

## **✨ OPTIMIZATIONS (Nice to Have)**

{{list each optimization with benefit description}}

## **🤖 LLM OPTIMIZATION (Token Efficiency & Clarity)**

{{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**

After presenting the suggestions, ask the user:

```
**IMPROVEMENT OPTIONS:**

Which improvements would you like me to apply to the story?

**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

Your choice:
```

### **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:

```
✅ **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.

**Success Criteria:** The LLM developer agent that processes your improved story will have:

- ✅ 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

**Every improvement should make it IMPOSSIBLE for the developer to:**

- Reinvent existing solutions
- Use wrong approaches or libraries
- Create duplicate functionality
- Miss critical requirements
- Make implementation errors

**LLM Optimization Should Make it IMPOSSIBLE for the developer agent to:**

- 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

**Go create the ultimate developer implementation guide! 🚀**