# VALIDATION Pattern: Quality Gates Across All Workflows

**Document:** `VALIDATION_SCRIPTS_BY_COMMAND.md`  
**Pattern:** VALIDATION (Cross-Cutting Quality Assurance)  
**Purpose:** Define validation gates and helper scripts that ensure quality at every stage of the workflow from docs to code to tests.  
**Status:** 🆕 NEW PATTERN (extracted from scattered validation logic in TESTING, RELEASE, PLANNING, IMPLEMENT patterns)

**Related Documentation:**
- [COMMAND-USE-CASE-PATTERNS.md](COMMAND-USE-CASE-PATTERNS.md) - Full pattern definitions
- [TESTING_SCRIPTS_BY_COMMAND.md](TESTING_SCRIPTS_BY_COMMAND.md) - TESTING pattern (now references VALIDATION)
- [CODE_ANALYSIS_SCRIPTS_BY_COMMAND.md](CODE_ANALYSIS_SCRIPTS_BY_COMMAND.md) - CODE-ANALYSIS pattern (now references VALIDATION)

---

## Executive Summary

### Problem: Validation Logic is Scattered

Validation requirements currently appear in multiple pattern documents:
- **TESTING pattern:** Gates 1, 2, 4, 5, 7 (configuration, docs, RED/GREEN state, handoffs)
- **RELEASE pattern:** Gates 1, 2, 3, 6, 7 (configuration, docs, GitHub connectivity, auto-closure, handoffs)
- **PLANNING pattern:** Gates 1, 2 (configuration, doc alignment)
- **IMPLEMENT pattern:** Gates 3, 5 (GitHub connectivity, minimal code scope)
- **CODE-ANALYSIS pattern:** Embedded validation in audit scripts

This creates:
- ❌ Code duplication across patterns
- ❌ Inconsistent validation approaches
- ❌ Validation logic tied to pattern logic
- ❌ Hard to update validation rules globally

### Solution: Unified VALIDATION Pattern

Extract validation into its own cross-cutting pattern:
- ✅ Reusable validation helpers (scripts)
- ✅ Consistent validation approach across patterns
- ✅ Decoupled validation from workflow logic
- ✅ Easy to enhance validation globally

---

## Validation Gates Framework

### 7 Core Validation Gates (Lifecycle Stages)

| Gate | Name | When | What to Validate | Who Uses |
|------|------|------|------------------|----------|
| **1** | Configuration Compliance | Before any work | cursorrules.md, ai-context.yml | RELEASE, PLANNING, IMPLEMENT |
| **2** | Documentation Quality | Before GitHub scoping | BRD/PRD/Spec comprehensiveness, clarity | RELEASE, PLANNING, TESTING |
| **3** | GitHub Connectivity | Before implementation | Issues, PRs, templates, connections | RELEASE, IMPLEMENT |
| **4** | Test-First Validation (RED) | Before code implementation | All tests fail (RED state) | TESTING, IMPLEMENT |
| **5** | Minimal Code Validation (GREEN) | Before PR creation | Tests pass, scope matches criteria | IMPLEMENT, CODE-ANALYSIS |
| **6** | Auto-Closure | After PR merge | Issues close, metadata updates | RELEASE, TESTING |
| **7** | Data Flow Handoffs | Between commands | Schemas validated, references correct | All patterns |

---

## Helper Scripts by Category

### Category 1: Configuration Validation

#### validate-cursorrules-compliance.ts (100-150 tokens)

**Purpose:** Verify cursorrules.md has required sections

**Functions:**
- `validateCursorrules()` - Check required sections exist
- `validateAuthenticationSetup()` - See .cursor/rules/03-github.mdc for auth setup
- `validateDefinitionOfDone()` - See .cursor/rules/07-project-patterns.mdc for patterns
- `validateBranchStrategy()` - Dev/main branches specified
- `generateComplianceReport()` - Summary of findings

**Used by:** /validate-project-config, /scope-release (pre-flight)

**Distribution:** Yes

---

#### validate-ai-context.ts (100-150 tokens)

**Purpose:** Verify ai-context.yml has required fields

**Functions:**
- `validateAiContext()` - Check required fields populated
- `validateDeploymentMethod()` - GitHub Actions, Vercel, Docker, etc.
- `validateTestFramework()` - Jest, Playwright, pytest, etc.
- `validateBaseBranch()` - Dev or main specified
- `validateSchemaManagement()` - Prisma, SQL, TypeORM, etc.
- `generateContextReport()` - Summary of metadata

**Used by:** /validate-project-config, /scope-release (pre-flight)

**Distribution:** Yes

---

### Category 2: Documentation Validation

#### validate-doc-structure.ts (150-200 tokens)

**Purpose:** Check BRD/PRD/Spec format and structure

**Functions:**
- `validateBRDStructure()` - Business context, success metrics, stakeholders, timeline, risks
- `validatePRDStructure()` - User stories, acceptance criteria, requirements, dependencies
- `validateSpecStructure()` - Technical approach, endpoints, data structures, testing strategy
- `validateHeadings()` - Ensure all required sections present
- `validateFormat()` - YAML frontmatter, markdown syntax
- `generateStructureReport()` - What's missing

**Used by:** /validate-release-docs, /guide-release

**Distribution:** Yes

---

#### validate-doc-comprehensiveness.ts (150-200 tokens)

**Purpose:** Check if documentation is actually complete and clear

**Functions:**
- `detectAmbiguousLanguage()` - Find vague terms (nice-to-have, user-friendly, etc.)
- `checkWordCount()` - Ensure sections have sufficient detail (>100 words for detailed sections)
- `validateAcceptanceCriteria()` - Check if testable (Given/When/Then format)
- `validateSuccessMetrics()` - Specific and measurable (not "work well")
- `validateTechnicalDetails()` - Has signatures, data structures, integration points
- `calculateCompletenessScore()` - % complete (0-100)
- `generateComprehensiveReport()` - Issues with specific line references

**Used by:** /validate-release-docs, /guide-release

**Distribution:** Yes

---

#### validate-cross-references.ts (100-150 tokens)

**Purpose:** Verify docs reference each other correctly

**Functions:**
- `validateBRDtoPRDreferences()` - PRD references BRD sections
- `validatePRDtoSpecReferences()` - Spec references PRD requirements
- `validateSpecToBRDreferences()` - Spec includes business context
- `validateSpecSectionReferences()` - Spec § references point to real sections
- `checkReferenceDepth()` - Ensure sections have sufficient content (>100 words)
- `generateReferenceMap()` - Visual map of cross-references
- `generateReferenceReport()` - Broken references, missing links

**Used by:** /validate-release-docs, /scope-release

**Distribution:** Yes

---

### Category 3: GitHub Artifact Validation

#### validate-issue-connectivity.ts (150-200 tokens)

**Purpose:** Verify GitHub issues are properly structured and linked

**Functions:**
- `validateReleaseIssueStructure()` - Has checklist, links to epics
- `validateEpicStructure()` - Has description, spec reference, child issues
- `validateChildIssueStructure()` - Has acceptance criteria, technical approach, dependencies
- `validateIssueLinks()` - Epic → Release link, Issue → Epic link
- `validateClassification()` - 1-10 scale, zone matches (1-3 ai-solo, 4-6 ai-led, etc.)
- `validateDependencies()` - Referenced issues exist
- `validateAcceptanceCriteria()` - Specific and testable
- `generateConnectivityReport()` - Missing links, orphaned issues

**Used by:** /scope-release (post-creation), /validate-github-issues

**Distribution:** Yes

---

#### validate-template-compliance.ts (100-150 tokens)

**Purpose:** Verify GitHub issue templates are properly formatted

**Functions:**
- `validateEnhancementTemplate()` - All sections present
- `validateBugTemplate()` - Steps to reproduce, expected vs actual
- `validateEpicTemplate()` - Goals, child issues, success metrics
- `validateFieldPresence()` - No placeholders or <!-- TODO -->
- `validateFieldFormat()` - Classification as 1-10, not prose
- `checkForPlaceholders()` - {{VARIABLE}} or <!-- TODO --> remaining
- `generateTemplateReport()` - Format issues

**Used by:** /validate-github-issues, /scope-release

**Distribution:** Yes

---

### Category 4: Code Validation

#### validate-code-style.ts (100-150 tokens)

**Purpose:** Check code style and naming conventions

**Used by:** /validate-code, review-code commands

**Distribution:** Yes (reference to audit-style.ts)

---

#### validate-code-security.ts (150-200 tokens)

**Purpose:** Identify security vulnerabilities

**Used by:** /validate-code, /audit-security commands

**Distribution:** Yes (reference to audit-security.ts)

---

#### validate-code-performance.ts (150-200 tokens)

**Purpose:** Find performance bottlenecks

**Used by:** /validate-code, /audit-performance commands

**Distribution:** Yes (reference to audit-performance.ts)

---

#### validate-code-complexity.ts (100-150 tokens)

**Purpose:** Measure code complexity

**Used by:** /validate-code, /audit-complexity commands

**Distribution:** Yes (reference to audit-complexity.ts)

---

### Category 5: Data Flow Validation

#### validate-schema.ts (150-200 tokens)

**Purpose:** Verify data schemas match expected interfaces

**Functions:**
- `validateEpicAnalysisSchema()` - Output from analyze-epic
- `validateImplementationPlanSchema()` - Output from plan-implementation
- `validateTestStrategySchema()` - Output from plan-implementation (critical)
- `validateTestsGeneratedSchema()` - Output from write-tests
- `validateImplementationResultSchema()` - Output from implement-issue
- `reportSchemaErrors()` - Missing fields, wrong types, invalid values

**Used by:** All commands with structured output (analyze-epic, plan-implementation, write-tests, implement-issue)

**Distribution:** Yes

---

#### validate-handoffs.ts (150-200 tokens)

**Purpose:** Verify data flows correctly between commands

**Functions:**
- `validateHandoff_CreateReleaseDocs_to_AdvanceRelease()` - BRD/PRD/Spec files exist
- `validateHandoff_AdvanceRelease_to_GuideRelease()` - current-release.md populated
- `validateHandoff_GuideRelease_to_ScopeRelease()` - current-release.md enriched
- `validateHandoff_ScopeRelease_to_Autopilot()` - GitHub issues created with numbers
- `validateHandoff_AnalyzeEpic_to_PlanImplementation()` - TOC sequenced issues valid
- `validateHandoff_PlanImplementation_to_WriteTests()` - Test strategy JSON valid (CRITICAL)
- `validateHandoff_WriteTests_to_ImplementIssue()` - Test files created, RED state proven
- `validateHandoff_ImplementIssue_to_CreateReleasePR()` - Code complete, tests GREEN

**Used by:** autopilot, implement-epic orchestrators

**Distribution:** Yes

---

#### validate-references.ts (100-150 tokens)

**Purpose:** Verify all references exist and are meaningful

**Functions:**
- `validateSpecReferences()` - Spec § references point to real sections
- `validateIssueReferences()` - GitHub issue #N references exist
- `validateDependencyReferences()` - Depends-on issues exist
- `validateBlocksReferences()` - Blocks issues exist
- `validateFileReferences()` - Referenced files exist in repo
- `generateReferenceReport()` - Broken references

**Used by:** /scope-release, /validate-github-issues

**Distribution:** Yes

---

### Category 6: Test State Validation

#### validate-red-state.ts (150-200 tokens)

**Purpose:** Prove generated tests fail (RED state)

**Functions:**
- `runTestSuite(framework)` - Execute tests (Jest, Playwright, pytest)
- `parseTestResults(output, framework)` - Parse runner output
- `countFailures()` - Total failed tests
- `countPasses()` - Should be 0 for RED state
- `validateAllTestsFail()` - 100% failure rate
- `generateFailureProof()` - Show test runner output as proof
- `generateFailureReport()` - RED state validation report

**Used by:** /write-tests, validate-test-state commands

**Distribution:** Yes

---

#### validate-green-state.ts (150-200 tokens)

**Purpose:** Prove implementation tests pass (GREEN state)

**Functions:**
- `runTestSuite(framework)` - Execute tests
- `parseTestResults(output, framework)` - Parse runner output
- `countFailures()` - Should be 0 for GREEN state
- `countPasses()` - Total passing tests
- `validateAllTestsPass()` - 100% pass rate
- `validateCoverageThreshold()` - Coverage > 35%
- `generatePassProof()` - Show test runner output as proof
- `generateGreenStateReport()` - GREEN state validation report

**Used by:** /implement-issue, before creating PR

**Distribution:** Yes

---

## Orchestrator Commands

### /validate-project-config (FREE)

**Tier:** FREE (basic project validation)

**Inputs:** cursorrules.md, ai-context.yml

**Process:**
1. Run validate-cursorrules-compliance.ts
2. Run validate-ai-context.ts
3. Aggregate findings

**Output:**
```
✅ Project Configuration Validation
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

.cursor/rules/: ✅ Complete
├─ Authentication setup (.cursor/rules/03-github.mdc): ✅
├─ Definition of Done (.cursor/rules/07-project-patterns.mdc): ✅
├─ Branch strategy: ✅ (dev → main)
└─ Coding standards: ✅

ai-context.yml: ✅ Complete
├─ Deployment method: ✅ (GitHub Actions)
├─ Test framework: ✅ (Jest)
├─ Base branch: ✅ (dev)
└─ Schema management: ✅ (Prisma)

Status: ✅ READY FOR RELEASE
```

**Used by:** /guide-release, /scope-release (pre-flight)

**Distribution:** Yes

---

### /validate-release-docs (STARTER)

**Tier:** STARTER (comprehensive doc validation)

**Inputs:** context/brds/, context/prds/, context/specs/

**Process:**
1. For each BRD/PRD/Spec file:
   - validate-doc-structure.ts
   - validate-doc-comprehensiveness.ts
   - validate-cross-references.ts
2. Aggregate findings

**Output:**
```
✅ Release Documentation Validation
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Issues found:
❌ PRD: Missing acceptance criteria for Issue #2
❌ Spec: Ambiguous language "user-friendly" (line 45)
⚠️  BRD: Only 85% complete (missing risk assessment)

OR

✅ All documents properly structured and comprehensive.
```

**Used by:** /guide-release, before /scope-release

**Distribution:** Yes

---

### /validate-github-issues (STARTER)

**Tier:** STARTER (GitHub issue validation)

**Inputs:** Release issue #N, all child epic and issue numbers

**Process:**
1. validate-issue-connectivity.ts (structure and links)
2. validate-template-compliance.ts (format)
3. validate-references.ts (spec § references)

**Output:**
```
✅ GitHub Issues Validation
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Release #123: ✅ Valid structure, all epics linked
Epic #124-126: ✅ All have spec references
Issues #127-150: ✅ All have classification

Status: ✅ READY FOR IMPLEMENTATION
```

**Used by:** /scope-release (post-creation), /analyze-epic

**Distribution:** Yes

---

### /validate-code (STARTER)

**Tier:** STARTER (code quality validation)

**Inputs:** Implementation code

**Process:**
1. validate-code-style.ts (calls audit-style.ts)
2. validate-code-security.ts (calls audit-security.ts)
3. validate-code-performance.ts (calls audit-performance.ts)
4. validate-code-complexity.ts (calls audit-complexity.ts)

**Output:**
```
✅ Code Validation Report
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Style: ✅ 0 issues
Security: ✅ 0 issues
Performance: ⚠️  1 warning (N+1 query on line 45)
Complexity: ✅ All functions < 10 cyclomatic complexity

Status: ✅ READY FOR TESTING (fix performance warning first)
```

**Used by:** review-code, before test execution

**Distribution:** Yes

---

### /validate-test-state (STARTER)

**Tier:** STARTER (test validation)

**Inputs:** Test files, test framework

**Process:**
1. Call validate-red-state.ts OR validate-green-state.ts based on phase

**Output (RED state):**
```
✅ Test State Validation (RED)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Total tests: 42
Failed (RED): ✅ 42/42 (100%)
Passed: ❌ 0/42 (0%)

Status: ✅ READY FOR IMPLEMENTATION
```

**Output (GREEN state):**
```
✅ Test State Validation (GREEN)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Total tests: 42
Failed: ❌ 0/42 (0%)
Passed: ✅ 42/42 (100%)
Coverage: ✅ 42% (> 35% threshold)

Status: ✅ READY FOR PR & MERGE
```

**Used by:** /write-tests (RED validation), /implement-issue (GREEN validation)

**Distribution:** Yes

---

## Validation Gate Application by Pattern

### PLANNING Pattern → RELEASE Pattern Handoff

**Gate 1: Configuration Compliance**
- Where: /guide-release Phase 1, before /scope-release
- Check: `.cursorrules.md` and `ai-context.yml` complete
- Helper: validate-cursorrules-compliance.ts, validate-ai-context.ts
- Fail: "Cannot scope release without project configuration"

**Gate 2: Documentation Quality**
- Where: /guide-release Phase 2, before /scope-release
- Check: BRD/PRD/Spec comprehensive and clear
- Helper: validate-doc-structure.ts, validate-doc-comprehensiveness.ts
- Fail: "Fix documentation gaps before creating GitHub issues"

---

### RELEASE Pattern → IMPLEMENT Pattern Handoff

**Gate 3: GitHub Connectivity**
- Where: /scope-release post-creation, /analyze-epic pre-analysis
- Check: All issues created, linked, numbered
- Helper: validate-issue-connectivity.ts, validate-template-compliance.ts
- Fail: "Verify all issues exist in GitHub before implementing"

**Gate 7: Data Flow Handoffs**
- Where: /scope-release → /autopilot transition
- Check: GitHub issues have all required fields
- Helper: validate-references.ts, validate-handoffs.ts
- Fail: "GitHub issues incomplete, cannot proceed to implementation"

---

### IMPLEMENT Pattern: Code Generation

**Gate 5: Minimal Code Validation (GREEN)**
- Where: /implement-issue before creating PR
- Check: All tests pass, no extra features
- Helper: validate-green-state.ts
- Fail: "Tests failing, cannot merge. Fix implementation."
- Success: "All tests GREEN, ready for PR"

---

### TESTING Pattern: Test Generation

**Gate 4: Test-First Validation (RED)**
- Where: /write-tests before approval
- Check: All tests fail (RED state)
- Helper: validate-red-state.ts
- Fail: "Some tests pass. Generated tests should all fail initially."
- Success: "All 42 tests failing. Ready for implementation."

---

## Tier Structure

### FREE Tier Validation Commands
- `/validate-project-config` - Basic cursorrules + ai-context check
- **Used by:** Free tier patterns (RELEASE, PLANNING)

### STARTER Tier Validation Commands
- `/validate-release-docs` - Doc structure + comprehensiveness
- `/validate-github-issues` - Issue connectivity + templates
- `/validate-code` - Code style, security, perf, complexity
- `/validate-test-state` - RED/GREEN state proof
- **Used by:** Starter tier patterns (all except CODE-ANALYSIS uses its own audit commands)

### ENTERPRISE Tier Validation Commands (Future)
- `/validate-multi-repo` - Cross-repo issue connectivity, schema alignment
- `/validate-deployment` - Multi-repo deployment validation

---

## Helper Script Token Impact

| Script | Tokens | Used By | Reuse Factor |
|--------|--------|---------|--------------|
| validate-cursorrules-compliance.ts | 100-150 | validate-project-config, scope-release | 2 |
| validate-ai-context.ts | 100-150 | validate-project-config, scope-release | 2 |
| validate-doc-structure.ts | 150-200 | validate-release-docs, guide-release | 2 |
| validate-doc-comprehensiveness.ts | 150-200 | validate-release-docs, guide-release | 2 |
| validate-cross-references.ts | 100-150 | validate-release-docs, scope-release | 2 |
| validate-issue-connectivity.ts | 150-200 | validate-github-issues, scope-release | 2 |
| validate-template-compliance.ts | 100-150 | validate-github-issues, scope-release | 2 |
| validate-schema.ts | 150-200 | All commands with structured output | 5-8 |
| validate-handoffs.ts | 150-200 | autopilot, implement-epic | 2 |
| validate-references.ts | 100-150 | scope-release, validate-github-issues | 2 |
| validate-red-state.ts | 150-200 | write-tests | 1 |
| validate-green-state.ts | 150-200 | implement-issue | 1 |
| **Total New Tokens** | **1.6-2.1K** | | |

**Token Savings from Refactoring:**
- TESTING pattern: -200 lines (~150-200 tokens)
- RELEASE pattern: -300 lines (~250-300 tokens)
- PLANNING pattern: -100 lines (~100-150 tokens)
- **Total Savings: -550 lines (~500-650 tokens)**

**Net Result:** +950-1450 tokens in new validation helpers, -500-650 tokens from refactoring = **+300-800 tokens with 3-4x more validation capability**

---

## Implementation Priority

### Phase 1: Foundation (Week 1)
- [ ] validate-cursorrules-compliance.ts
- [ ] validate-ai-context.ts
- [ ] /validate-project-config orchestrator
- **Unblocks:** RELEASE pattern validation

### Phase 2: Documentation (Week 2)
- [ ] validate-doc-structure.ts
- [ ] validate-doc-comprehensiveness.ts
- [ ] validate-cross-references.ts
- [ ] /validate-release-docs orchestrator
- **Unblocks:** scope-release validation

### Phase 3: GitHub Artifacts (Week 3)
- [ ] validate-issue-connectivity.ts
- [ ] validate-template-compliance.ts
- [ ] validate-references.ts
- [ ] /validate-github-issues orchestrator
- **Unblocks:** analyze-epic validation

### Phase 4: Code & Tests (Week 4)
- [ ] validate-schema.ts (critical for Implement Pattern)
- [ ] validate-red-state.ts (critical for write-tests)
- [ ] validate-green-state.ts (critical for implement-issue)
- [ ] /validate-code orchestrator
- [ ] /validate-test-state orchestrator
- **Unblocks:** Implement Pattern workflow

### Phase 5: Data Flows (Week 5)
- [ ] validate-handoffs.ts
- [ ] Integration testing across patterns
- **Unblocks:** Orchestration improvements

---

## Summary

**VALIDATION Pattern provides:**
- ✅ 12 reusable helper scripts (1.6-2.1K tokens)
- ✅ 5 orchestrator commands (/validate-project-config, /validate-release-docs, /validate-github-issues, /validate-code, /validate-test-state)
- ✅ 7 validation gates applicable across all patterns
- ✅ Consistent validation approach (no duplication)
- ✅ Decoupled from pattern logic
- ✅ -500-650 tokens from refactoring (offset by new helpers)
- ✅ 3-4x more validation capability

**Impact on other patterns:**
- TESTING: Simplify by removing validation details, reference VALIDATION pattern
- RELEASE: Simplify by removing validation details, reference VALIDATION pattern
- PLANNING: Simplify by removing validation details, reference VALIDATION pattern
- IMPLEMENT: Simplify by removing validation details, reference VALIDATION pattern
- CODE-ANALYSIS: Keep audit scripts, integrate with /validate-code orchestrator