---
roadcrew_template_name: "validate-release-docs.md"
roadcrew_template_type: "command"
execution_mode: "auto-execute"
roadcrew_template_version: "v1.0"
roadcrew_last_updated: "2025-10-25"
roadcrew_min_version: "1.5.0"
roadcrew_license: "See LICENSE file in .roadcrew folder"
roadcrew_copyright: "Copyright (c) 2025 North Star Holdings, LLC"
spdx_license_identifier: "LicenseRef-RoadcrewLicense-1.0"
---
### validate-release-docs

**Command File**: `validate-release-docs.md`  
**Implementation**: `scripts/validate-release-docs.ts`

**Purpose**: Validate generated BRD, PRD, and Spec documents to ensure they meet template requirements and will work correctly with downstream commands (`guide-release`, `scope-release`).

**Usage**:

In Cursor Chat:
```
/validate-release-docs                    # Validates most recent docs in each folder
/validate-release-docs submodule-isolation
/validate-release-docs --brd context/brds/feature-brd.md --prd context/prds/feature-prd.md --spec context/specs/feature-spec.md
```

From terminal:
```bash
npm run validate-release-docs              # Validates most recent docs
npm run validate-release-docs submodule-isolation
npm run validate-release-docs -- --spec context/specs/feature-spec.md
```

**What it does**:

1. **Locates Documents**: Finds BRD, PRD, and Spec files (latest by modification time or specified)
2. **Validates BRD Structure**: Checks sections, pricing table, GTM roadmap, metrics
3. **Validates PRD Structure**: Checks requirements, user stories, **Section 9 Mapping to Spec**
4. **Validates Spec Structure**: Checks **Section 1 PRD Mapping** and **Section 8 Issue Breakdown**
5. **Issue Breakdown Deep Validation**: Ensures every issue has all 7 required fields in correct format
6. **Classification Format Check**: Verifies classifications are numbers (1-10), not zone names
7. **Length Limit Verification**: Checks word counts for overviews, bullets
8. **Cross-Reference Validation**: Verifies BRD ↔ PRD ↔ Spec links exist and are correct
9. **Reports Results**: Shows ✅/❌ for each check with actionable fix suggestions

**Parameters**:
- `feature-id` (optional): Validates docs matching this feature ID
- `--brd` (optional): Path to specific BRD file
- `--prd` (optional): Path to specific PRD file
- `--spec` (optional): Path to specific Spec file

**Validation Checks**:

### BRD Validation (`context/brds/*.md`)

**Structure Checks:**
- ✅ YAML frontmatter present with required fields (type, title, feature_id, status)
- ✅ Section 1: Executive Summary exists (≤40 words)
- ✅ Section 2: Business Context exists (≤4 bullets per subsection)
- ✅ Section 3: Business Goals exists (≤5 goals, ≤15 words each)
- ✅ Section 4: Non-Goals exists (≤3, ≤12 words each)
- ✅ Section 5: Pricing Model table exists (≤3 tiers)
- ✅ Section 6: GTM Roadmap exists (≤3 phases)
- ✅ Section 7: Metrics exists (split across 3 categories: Product/Financial/Usage)
- ✅ Section 8: Risks & Mitigations table exists (≤4 risks)
- ✅ Section 9: References & Downstream links present

**Content Checks:**
- ✅ Pricing table has columns: Tier, Price, Key Features, Audience
- ✅ Metrics split into exactly 3 subsections (7.1, 7.2, 7.3)
- ✅ Related PRD/Spec paths are valid

**Not Critical:** BRD is reference document, doesn't block downstream commands if incomplete

---

### PRD Validation (`context/prds/*.md`) ⚠️ IMPORTANT

**Structure Checks:**
- ✅ YAML frontmatter present with required fields (type, feature, feature_id, status, related_spec)
- ✅ Section 1: Business & User Goals exists
- ✅ Section 2: Problem Statement exists (≤40 words)
- ✅ Section 3: Success Metrics exists (split into 3 subsections)
- ✅ Section 4: Requirements exists with 4.1 Functional (≤6, ≤15 words each)
- ✅ Section 5: User Stories table exists
- ✅ Section 6: User Journey table exists (≤5 steps)
- ✅ Section 7: Non-Goals exists (≤3)
- ✅ Section 8: Impact & Dependencies exists
- ✅ **Section 9: Mapping to Spec exists** 🔥 CRITICAL

**Section 9 Deep Validation:** 🔥
- ✅ Has table with columns: "Functional Requirement" and "Spec Section"
- ✅ All R1-R6 requirements from Section 4.1 are listed in mapping table
- ✅ Each requirement maps to a valid spec section number (e.g., "2.1.1", "3.2")
- ❌ **FAIL if:** Section 9 missing, incomplete, or requirements don't match Section 4.1

**Content Checks:**
- ✅ Functional requirements are numbered R1-R6
- ✅ User Stories table has columns: ID, As a, I want to, So that I can
- ✅ Related Spec path exists and is valid

---

### Spec Validation (`context/specs/*.md`) ⚠️ MOST CRITICAL

**Structure Checks:**
- ✅ YAML frontmatter present with required fields (type, feature, feature_id, status, related_prd)
- ✅ Section 1: Mapping: PRD → Spec exists 🔥 CRITICAL
- ✅ Section 2: Technical Requirements exists
- ✅ Section 3: Design Overview exists (≤100 words)
- ✅ Section 4: Architecture & Implementation exists
- ✅ Section 5: Execution Plan & Issues exists
- ✅ Section 6: Testing & Validation exists
- ✅ Section 7: Dependencies & Links exists
- ✅ **Section 8: Issue Breakdown exists** 🔥 CRITICAL

**Section 1 Deep Validation:** 🔥
- ✅ Has table with columns: "PRD Requirement" and "Satisfied In Spec Section"
- ✅ All PRD requirements (R1-R6) are listed in mapping table
- ✅ Each requirement maps to a valid spec section (e.g., "2.1.1", "4.2")
- ❌ **FAIL if:** Section 1 missing, incomplete, or doesn't match PRD Section 9

**Section 8 Issue Breakdown - Deep Validation:** 🔥 CRITICAL FOR SCOPE-RELEASE

For **EACH** issue in Section 8, validate:

**Format:**
```markdown
### Issue X.Y: Title {#issue-X-Y}
- **Overview:** (text)
- **Accepts:** (bullets)
- **Tech Approach:** (bullets)
- **Files/Components:** (list)
- **Dependencies:** (value)
- **Classification:** (number)
- **Size/Complexity:** (value)
```

**Required Checks Per Issue:**

1. **Heading Format:**
   - ✅ Starts with `### Issue`
   - ✅ Has format: `Issue X.Y: Title {#issue-X-Y}`
   - ✅ Has anchor tag `{#issue-X-Y}`

2. **Overview Field:**
   - ✅ Present: `- **Overview:**`
   - ✅ Length: ≤50 words
   - ✅ Not empty placeholder

3. **Accepts Field:**
   - ✅ Present: `- **Accepts:**`
   - ✅ Has 1-5 bullet points
   - ✅ Each bullet ≤12 words
   - ✅ Format: pass/fail criteria or Given/When/Then

4. **Tech Approach Field:**
   - ✅ Present: `- **Tech Approach:**`
   - ✅ Has 1-6 bullet points
   - ✅ Lists files, components, or implementation steps

5. **Files/Components Field:**
   - ✅ Present: `- **Files/Components:**`
   - ✅ Lists at least one file or component

6. **Dependencies Field:** 🔥 CRITICAL
   - ✅ Present: `- **Dependencies:**`
   - ✅ Format: `#N, #M` OR `None` OR `Issue X.Y`
   - ❌ **FAIL if:** Missing or ambiguous (e.g., "TBD", "See above")

7. **Classification Field:** 🔥 CRITICAL FOR ASSIGNMENT
   - ✅ Present: `- **Classification:**`
   - ✅ **Format: NUMBER 1-10** (not zone name)
   - ❌ **FAIL if:** Uses zone name ("ai-solo", "ai-led", etc.)
   - ❌ **FAIL if:** Outside 1-10 range
   - ❌ **FAIL if:** Missing or "TBD"

8. **Size/Complexity Field:**
   - ✅ Present: `- **Size/Complexity:**`
   - ✅ Format: `S/S`, `M/M`, `L/L`, or `S/M`, etc.
   - ✅ Both size and complexity present (separated by `/`)

**Cross-Reference Checks:**
- ✅ Related PRD path in frontmatter exists and is valid
- ✅ Related BRD path exists (if linked in Section 7)
- ✅ Dependencies reference valid issue numbers

---

## Output Format

**Summary Report:**
```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✅ VALIDATION REPORT: Submodule Isolation
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📊 BRD: context/brds/submodule-isolation-brd.md
   ✅ Structure: 9/9 sections present
   ✅ Pricing: 3 tiers, all columns present
   ✅ Metrics: Split across 3 categories
   ✅ Cross-refs: PRD link valid

📝 PRD: context/prds/submodule-isolation-prd.md
   ✅ Structure: 9/9 sections present
   ✅ Requirements: R1-R6 numbered, ≤15 words each
   ✅ Section 9: All 6 requirements mapped to spec
   ✅ Cross-refs: BRD + Spec links valid

⚙️ Spec: context/specs/submodule-isolation-spec.md
   ✅ Structure: 8/8 sections present
   ✅ Section 1: All 6 PRD requirements mapped
   ✅ Section 8: 8 issues found
   
   Issue Breakdown Validation:
   ✅ Issue 1.1: All 7 fields present, Classification=5
   ✅ Issue 1.2: All 7 fields present, Classification=3
   ✅ Issue 2.1: All 7 fields present, Classification=7
   ✅ Issue 2.2: All 7 fields present, Classification=4
   ✅ Issue 2.3: All 7 fields present, Classification=6
   ✅ Issue 3.1: All 7 fields present, Classification=8
   ✅ Issue 4.1: All 7 fields present, Classification=5
   ✅ Issue 4.2: All 7 fields present, Classification=6

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✅ VALIDATION PASSED: Ready for /guide-release and /scope-release
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```

**If Errors Found:**
```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
❌ VALIDATION FAILED: Submodule Isolation
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

⚙️ Spec: context/specs/submodule-isolation-spec.md

   Issue Breakdown Validation:
   ✅ Issue 1.1: All 7 fields present, Classification=5
   ❌ Issue 1.2: Classification uses zone name "ai-led" instead of number
      FIX: Change to "- **Classification:** 5"
   
   ❌ Issue 2.1: Dependencies field missing
      FIX: Add "- **Dependencies:** None" or "#1.1, #1.2"
   
   ✅ Issue 2.2: All 7 fields present, Classification=4
   
   ❌ Issue 2.3: Overview exceeds 50 words (63 words found)
      FIX: Reduce to ≤50 words

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
❌ CRITICAL ISSUES FOUND: 3
   Fix these before running /scope-release
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

QUICK FIXES:
1. Issue 1.2: Line 127 - Change "ai-led" → "5"
2. Issue 2.1: Line 156 - Add "- **Dependencies:** None"
3. Issue 2.3: Line 178 - Reduce Overview from 63 to ≤50 words
```

---

## Common Issues & Fixes

### Issue 1: Classification uses zone names
**Error:** `- **Classification:** ai-led`  
**Fix:** `- **Classification:** 5`  
**Why:** `scope-release` needs numbers for assignment routing

### Issue 2: Missing Dependencies field
**Error:** Field not present  
**Fix:** Add `- **Dependencies:** None` or `#1.1, #2.3`  
**Why:** Required for issue ordering in `/implement-epic`

### Issue 3: Overview exceeds 50 words
**Error:** 63 words found  
**Fix:** Reduce to ≤50 words, focus on "what" not "why"  
**Why:** Maps to `enhancement.template.md` which has 50-word limit

### Issue 4: Section 9 missing in PRD
**Error:** PRD has no "Mapping to Spec" section  
**Fix:** Add Section 9 table mapping R1-R6 to spec sections  
**Why:** Spec needs this to create inverse mapping in Section 1

### Issue 5: Size/Complexity format wrong
**Error:** `- **Size/Complexity:** Medium`  
**Fix:** `- **Size/Complexity:** M/M`  
**Why:** Must be `Size/Complexity` format (e.g., `S/M`, `L/L`)

---

## Requirements

- At least one of BRD, PRD, or Spec must exist in respective directories
- If `feature-id` specified, files must match naming: `[feature-id]-{brd,prd,spec}.md`
- Spec Section 8 is **REQUIRED** for validation to pass (needed for `scope-release`)

## Success Criteria

**Validation PASSES if:**
- ✅ All required sections present in each document
- ✅ PRD Section 9 complete and matches Section 4.1 requirements
- ✅ Spec Section 1 complete and matches PRD requirements
- ✅ **ALL issues in Spec Section 8 have 7 required fields**
- ✅ **ALL Classifications are numbers 1-10 (not zone names)**
- ✅ **ALL Dependencies are explicit (not "TBD" or missing)**
- ✅ Cross-references (BRD ↔ PRD ↔ Spec) are valid

**Validation FAILS if:**
- ❌ Any issue missing required fields
- ❌ Any Classification uses zone name instead of number
- ❌ Any Dependencies missing or ambiguous
- ❌ PRD Section 9 or Spec Section 1 missing/incomplete
- ❌ Word count limits exceeded

---

## Next Steps After Validation

**If validation passes:**
1. ✅ Proceed with `/guide-release` to populate `future-releases.md`
2. ✅ Then run `/scope-release` to create GitHub issues

**If validation fails:**
1. 🔧 Fix reported issues in the spec (most critical)
2. 🔧 Fix PRD/BRD issues if any
3. 🔄 Run `/validate-release-docs` again
4. ✅ Once passing, proceed with `/guide-release`

---

**Note:** This command only **validates** documents. It does not modify them. All fixes must be applied manually or via another command.