---
roadcrew_template_name: "validate-release.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

Pre-flight validation for release files before creating GitHub issues.

## What This Command Does

Validates `current-release.md` or `minor-release.md` to ensure:
1. All issues are fully enriched (no TODO placeholders)
2. Classification scores and zones are correct
3. Dependencies reference valid issues
4. File references are accurate
5. Acceptance criteria meet quality standards

## Prerequisites

- Release file exists (`memory-bank/releases/current-release.md` or `memory-bank/releases/minor-release.md`)
- TypeScript project built (runs automatically)

## Usage

```bash
# Validate current release (default)
/validate-release
/validate-release --current

# Validate minor release
/validate-release --minor

# Validate specific file
/validate-release --file memory-bank/releases/custom-release.md
```

## Command Execution

This command runs the TypeScript script:
- **Instance installation:** `scripts/validate-release.ts`
- **Submodule installation:** `.roadcrew/scripts/validate-release.ts` or `roadcrew/scripts/validate-release.ts`

**Flags:**
- `--current` - Validate current-release.md (default)
- `--minor` - Validate minor-release.md
- `--file <path>` - Validate custom release file

## Validation Checks

### 1. Classification Validation
- ✓ Scores are 1-10 (valid range)
- ✓ Zone matches score:
  - 1-3 → ai-solo
  - 4-6 → ai-led
  - 7-8 → ai-assisted
  - 9-10 → ai-limited

### 2. Completeness Validation
- ✓ Overview & User Story present
- ✓ Acceptance Criteria defined
- ✓ Technical Implementation detailed
- ✓ Dependencies mapped
- ✓ Estimated Effort calculated (no TBD)

### 3. Dependency Validation
- ✓ Dependencies reference valid issue numbers
- ✓ No circular dependencies
- ⚠️ Warns on orphaned references

### 4. File Reference Validation
- 💡 Flags references to files not in tech-stack.md
- 💡 Suggests verification for new files

### 5. Quality Validation
- ⚠️ Warns if <3 or >8 acceptance criteria
- ⚠️ Flags missing file paths for high-complexity issues
- 💡 Suggests classification review if criteria don't match complexity

## Output Format

```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🔍 VALIDATING RELEASE
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📄 File: current-release.md
   Lines: 2748

✓ Parsed 34 issues

Running validation checks...

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📊 VALIDATION RESULTS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

✅ Issues Validated: 34
❌ Errors: 0
⚠️  Warnings: 3
💡 Info: 5

⚠️  WARNINGS (Recommended):
────────────────────────────────────────────────────

Issue 2.2: Only 2 acceptance criteria (recommend 3-5)
   💡 Add more specific, testable criteria

Issue 3.2: References new file: scripts/utils/resource-assigner.ts
   💡 Verify this file will be created in this issue or earlier

Issue 6.1: Classification 8 but no file references in implementation
   💡 Add specific file paths to technical implementation

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✅ VALIDATION PASSED

Ready for: /scope-release --current
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```

## Issue Severity Levels

**❌ ERRORS (Must Fix)**
- Invalid classification scores or zones
- Missing required sections
- Circular dependencies
- Issues still showing TODO placeholders
- Exit code: 1 (blocks /scope-release)

**⚠️ WARNINGS (Recommended)**
- Too few or too many acceptance criteria
- Missing file references for complex issues
- Dependencies referencing non-existent issues
- Exit code: 0 (can proceed with caution)

**💡 INFO (Review)**
- References to new files (might be created later)
- Classification vs criteria count mismatches
- Suggestions for improvement
- Exit code: 0

## Typical Workflow

```bash
# 1. Enrich release
/enrich-release

# 2. Validate (NEW STEP)
/validate-release --current

# 3. Review warnings, fix critical issues
# Edit current-release.md to address errors

# 4. Re-validate if needed
/validate-release --current

# 5. Create GitHub issues
/scope-release --current
```

## Common Issues & Fixes

### "Invalid classification: X should be zone Y"
**Cause:** Classification score doesn't match zone mapping
**Fix:** Update zone to match classification:
```markdown
**Classification**: 4 (ai-led)  # was (ai-solo), should be ai-led
```

### "Missing Overview & User Story section"
**Cause:** Issue still has TODO placeholder
**Fix:** Run `/enrich-release --from X.X` to complete enrichment

### "Circular dependency with Issue X.X"
**Cause:** Issue A depends on B, and B depends on A
**Fix:** Remove one of the dependencies, keeping only the primary dependency

### "Only 2 acceptance criteria (recommend 3-5)"
**Cause:** Issue has too few testable criteria
**Fix:** Add more specific, verifiable acceptance criteria

### "Classification 8 but no file references"
**Cause:** High-complexity issue lacks specific file paths
**Fix:** Add file paths to Technical Implementation section

## Integration with Other Commands

**Before /scope-release:**
```bash
/validate-release --current  # Pre-flight check
/scope-release --current     # Create issues if validation passes
```

**After /enrich-release:**
```bash
/enrich-release              # Enrich all issues
/validate-release --current  # Verify enrichment quality
```

**During manual editing:**
```bash
# Edit current-release.md
/validate-release --current  # Check your changes
```

## Exit Codes

- `0` - Validation passed (or warnings only)
- `1` - Validation failed (errors present)

## Notes

- Validation is non-destructive (read-only)
- Can be run multiple times
- Completes in <5 seconds for typical releases
- Does not require GitHub API access
- Uses tech-stack.md for file reference validation

## Success Criteria

✅ No errors → Ready for `/scope-release`
⚠️ Warnings only → Can proceed with caution
❌ Errors present → Fix before creating issues

---

**Related Commands:**
- `/enrich-release` - Populate issue details
- `/scope-release` - Create GitHub issues
- `/analyze-repo` - Update tech-stack.md context