# Story Context Quality Review

You are an independent quality validator in a fresh context. Thoroughly review the story file generated by the create-story workflow and identify any mistakes, omissions, or gaps the original pass missed.

**Focus on preventing:**

- Reinventing existing functionality
- Wrong libraries, versions, or file locations
- Breaking regressions or ignoring UX requirements
- Vague or incomplete acceptance criteria
- Missing learnings from previous stories

## Required Inputs

- Story file to review (`{story_file_path}`)
- Workflow variables from `{installed_path}/workflow.yaml` (implementation_artifacts, epics_file, etc.)
- Source documents: epics, architecture (discovered or provided)

---

## Systematic Re-Analysis

Systematically re-do the story creation process with a critical eye for what the original pass missed:

### **Step 1: Load and Understand the Target**

1. Load `{installed_path}/workflow.yaml` for variable inclusion
2. Load the story file `{story_file_path}`; extract epic_num, story_num, story_key, story_title
3. Resolve all workflow variables: implementation_artifacts, epics_file, architecture_file, etc.

### **Step 2: Exhaustive Source Document Analysis**

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

#### **3.1 Reinvention Gaps**

- Duplicate functionality that could be reused instead
- Existing solutions not referenced

#### **3.2 Technical Specification Gaps**

- Missing version requirements, API contracts, database schema constraints, security requirements

#### **3.3 File Structure Gaps**

- Wrong file locations, coding standard violations, integration pattern breaks, deployment requirements

#### **3.4 Regression Gaps**

- Breaking changes, test failures, UX violations, learnings from previous stories ignored

#### **3.5 Implementation Gaps**

- Vague acceptance criteria, missing scope boundaries, quality requirements

### **Step 4: LLM Optimization Analysis**

Review the story for token efficiency: remove verbosity, fix ambiguity, ensure critical requirements are surfaced clearly, and structure content for scannable LLM processing.

### **Step 5: Improvement Recommendations**

For each gap identified, provide specific actionable improvements categorized as:

- **Critical (Must Fix):** Missing requirements, security gaps, anti-pattern risks, previous story context that would prevent errors
- **Enhancement (Should Add):** Architectural guidance, technical specs, code reuse opportunities, testing guidance
- **Optimization (Nice to Have):** Token-efficient phrasing, clearer structure, reduced verbosity

---

## Interactive Improvement Process

### **Step 6: Present Improvement Suggestions**

```
Story: {{story_key}} - {{story_title}}
Critical: {{critical_count}} | Enhancements: {{enhancement_count}} | Optimizations: {{optimization_count}}

CRITICAL ISSUES (Must Fix):
{{list each critical issue}}

ENHANCEMENTS (Should Add):
{{list each enhancement}}

OPTIMIZATIONS (Nice to Have):
{{list each optimization}}
```

### **Step 7: Interactive User Selection**

Ask the user:

```
Which improvements to apply? [all / critical / select / none / details]
```

### **Step 8: Apply Selected Improvements**

- Load the story file and apply accepted changes naturally
- Do not reference the review process or that changes were added
- Ensure the final story reads as if it was created correctly the first time

### **Step 9: Confirmation**

```
Updated {{count}} sections in {{story_key}}.
Next: Run `dev-story` for implementation.
```
