# Validate Story Readiness for Parallel Development

## Purpose

Comprehensive validation of story readiness using a 3-tier system that balances quality enforcement with developer autonomy. Provides critical blocks, overrideable warnings, and helpful suggestions.

## Context

Parallel development amplifies the cost of poorly defined stories. This validation system helps teams identify risks while respecting their judgment to proceed when appropriate.

## Validation Tiers

### Tier 1: Critical (Blocking)

These issues prevent parallel execution entirely:

- Missing story title or description
- Invalid BMAD format
- Corrupted or unreadable story data

### Tier 2: Warning (Override with Justification)

These issues increase risk but can be overridden:

- Missing dev notes or implementation details
- No acceptance criteria defined
- Incomplete test specifications
- Unmapped dependencies
- High complexity without architect review

### Tier 3: Suggestion (Informational)

Best practice recommendations:

- Large story size (consider splitting)
- Potential duplication with existing stories
- Legacy system impacts

## Task Instructions

### 1. Load Story and Validation Rules

```yaml
[[LLM: Load the story content and applicable validation rules based on story type]]

# Load story
story_id: {{STORY_ID}}
story_type: {{STORY_TYPE}} # feature, bug, spike, research, tech-debt

# Load validation rules
- Base rules from config/validation-rules.yml
- Apply story type overrides
- Apply team-specific overrides if configured
```

### 2. Execute Validation Checks

#### Critical Validations

```yaml
[[LLM: Check for blocking issues]]

CRITICAL_CHECKS:
  - MISSING_TITLE: Story has a non-empty title
  - INVALID_FORMAT: Story follows BMAD structure
  - NO_DESCRIPTION: Story has meaningful description

If any critical check fails:
  status: BLOCKED
  message: "Cannot proceed with parallel development"
  action: Fix critical issues before continuing
```

#### Warning Validations

```yaml
[[LLM: Check for high-risk issues requiring justification]]

WARNING_CHECKS:
  - NO_DEV_NOTES:
      check: Dev Notes section has > 100 characters
      risk: "Parallel conflicts, duplicated work"

  - NO_ACCEPTANCE_CRITERIA:
      check: At least 2 acceptance criteria defined
      risk: "Unclear completion, testing gaps"

  - MISSING_TEST_SPECS:
      check: Test section includes scenarios
      risk: "Inconsistent testing across branches"

  - UNMAPPED_DEPENDENCIES:
      check: Dependencies section lists components/APIs
      risk: "Conflicting changes to shared code"

  - HIGH_COMPLEXITY_NO_REVIEW:
      check: Story points <= 8 OR has architect approval
      risk: "Architectural conflicts"
```

#### Suggestion Validations

```yaml
[[LLM: Check for improvement opportunities]]

SUGGESTION_CHECKS:
  - LARGE_STORY_SIZE:
      check: Story points <= 13
      recommendation: "Split into smaller stories"

  - SIMILAR_STORY_EXISTS:
      check: No similar titles in current sprint
      recommendation: "Verify no duplication"

  - LEGACY_SYSTEM_IMPACT:
      check: No legacy system tags
      recommendation: "Schedule domain expert review"
```

### 3. Generate Validation Report

```yaml
[[LLM: Create comprehensive validation report]]

VALIDATION_REPORT:
  story_id: {{STORY_ID}}
  story_title: {{STORY_TITLE}}
  validation_timestamp: {{TIMESTAMP}}

  summary:
    critical_issues: 0  # Must be 0 to proceed
    warnings: 2         # Can override with justification
    suggestions: 1      # Informational only

  details:
    critical: []

    warnings:
      - rule: NO_DEV_NOTES
        message: "Missing implementation details"
        risks:
          - "Merge conflicts due to unclear boundaries"
          - "Duplicated work across parallel branches"
        recommendation: "Add technical approach to Dev Notes"

      - rule: UNMAPPED_DEPENDENCIES
        message: "Dependencies not documented"
        risks:
          - "Breaking changes to shared components"
        recommendation: "List affected services/APIs"

    suggestions:
      - rule: LARGE_STORY_SIZE
        message: "Story seems large (13 points)"
        recommendation: "Consider splitting for better parallel execution"

  overall_risk_level: MEDIUM  # LOW, MEDIUM, HIGH, CRITICAL
```

### 4. Handle User Decision

#### If No Critical Issues:

```yaml
[[LLM: Present options based on validation results]]

If warnings exist:
  prompt: |
    ⚠️ VALIDATION WARNINGS (2 issues found)

    This story has the following risks for parallel development:

    1. Missing implementation details
       - Risk: Merge conflicts and duplicated work
       - Fix: Add technical approach to Dev Notes

    2. Dependencies not documented
       - Risk: Breaking changes to shared components
       - Fix: List affected services and APIs

    OPTIONS:
    [1] Fix issues and re-validate
    [2] Proceed with override (requires justification)
    [3] Cancel and return to backlog

    Your choice:

If user selects override:
  prompt: |
    Please provide justification for proceeding despite warnings:
    (This will be logged for process improvement)

    > [User enters justification]

  log_override:
    story_id: {{STORY_ID}}
    timestamp: {{TIMESTAMP}}
    user: {{USER_ID}}
    warnings_overridden: [NO_DEV_NOTES, UNMAPPED_DEPENDENCIES]
    justification: "{{USER_JUSTIFICATION}}"
    team: {{TEAM_ID}}
```

### 5. Just-In-Time Re-validation

```yaml
[[LLM: Re-validate when transitioning states]]

On state transition (e.g., Backlog → In Progress):

  # Quick re-check of critical items
  revalidate:
    - Story still exists
    - Dependencies haven't changed
    - No blocking issues introduced

  If new issues found:
    message: |
      ⚠️ Story validation has changed since last review

      New issue detected: {{ISSUE}}

      Please review before proceeding.
```

### 6. Learn from Override Patterns

```yaml
[[LLM: Analyze override logs periodically]]

Monthly analysis by SM agent:
  - Which rules are most frequently overridden?
  - Which teams override most often?
  - Common justification patterns

  Generate insights:
    - "NO_DEV_NOTES overridden 80% for spikes - consider rule adjustment"
    - "Team Alpha overrides 3x average - schedule process review"
    - "Acceptance criteria rule may be too strict for maintenance work"
```

## Output Format

### Validation Report with Quality Ratings

```yaml
Story Validation Report
======================
Story ID: {{STORY_ID}}
Title: {{STORY_TITLE}}

Quality Assessment:
- Story Completeness: ★★★☆☆ (3/5) - Missing dev notes
- Technical Clarity: ★★☆☆☆ (2/5) - Dependencies unmapped
- Test Coverage: ★★★★☆ (4/5) - Good test scenarios
- Risk Management: ★★★☆☆ (3/5) - Some risks unaddressed
- Parallel Readiness: ★★★☆☆ (3/5) - Needs improvement

Overall Quality Score: ★★★☆☆ (3.0/5)
Recommendation: Fix warnings before parallel execution

Validation Summary:
- ✅ Critical Checks: PASSED (0 issues)
- ⚠️  Warning Checks: FAILED (2 issues)
- 💡 Suggestions: 1 improvement opportunity

[Detailed findings follow...]
```

## Success Criteria

- All critical issues resolved before parallel execution
- Warnings either fixed or overridden with justification
- Override patterns analyzed for process improvement
- Developers feel empowered while understanding risks
- Quality ratings provide clear visual feedback

## Notes

- Validation rules can be customized per team in config/validation-rules.yml
- Override logs are preserved for retrospective analysis
- Cache validation results for 5 minutes to improve performance
- Different story types have different validation requirements