---
roadcrew_template_name: "validate-github-templates.md"
roadcrew_template_type: "command"
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"
execution_mode: "auto-execute"
---

# validate-github-templates

Validate GitHub issue/PR templates for spec compliance and recommend fixes.

> **Execution:** Runs immediately with automatic validation. Auto-fixes available with approval.

**Template locations:** `.github/ISSUE_TEMPLATE/`, `.github/pull_request_template.md`

Validates all epics and child issues in GitHub against the required template formats (@epic.template.md and @enhancement.template.md).

## Overview

This command fetches all open epics and their child issues from GitHub, then validates each issue to ensure:

1. **Epic Format Compliance** - All required sections present and filled
2. **Child Issue Format Compliance** - All required sections present and filled
3. **No Template Placeholders** - No `{{}}`, `TBD`, or `TODO:` variables remain
4. **Quality Checks** - Content meets minimum length requirements

**If all checks pass**, the script exits with success and displays next steps.
**If checks fail**, it provides detailed error messages and remediation guidance.

## Prerequisites

- GitHub repository with open epics labeled with `epic` label
- GitHub authentication configured (GH_TOKEN or GITHUB_TOKEN environment variable)
- All epics and child issues created in GitHub

## Usage

```bash
npm run validate-github-templates
```

Or directly:

```bash
npx ts-node scripts/validate-github-templates.ts
```

## What It Validates

### Epic Issues (must have label: epic)

**Required sections:**
- ✅ Overview (min 10 chars)
- ✅ Key Goals (bulleted list)
- ✅ Child Issues (links to #XXX)
- ✅ Dependencies (with "Depends on" and "Blocks")
- ✅ Definition of Done (checklist)

**Optional sections:**
- 📋 Related Spec (recommended)

### Child Issues (enhancement, bug, or feature)

**Enhancement/Feature:**
- ✅ Overview & User Story (min 10 chars)
- ✅ Acceptance Criteria (bulleted list)
- ✅ Technical Implementation (implementation details)
- ✅ Dependencies (with "Depends on" and "Blocks")
- ✅ Definition of Done (checklist)
- 📋 Estimated Effort (classification 1-10, optional)

**Bug:**
- ✅ Bug Description (min 10 chars)
- ✅ Steps to Reproduce (bulleted list)
- ✅ Expected Behavior (description)
- ✅ Actual Behavior (description)
- ✅ Definition of Done (checklist)

### Quality Checks

For each section:
- 🚫 **Error** - Section missing or contains unfilled placeholders
- ⚠️ **Warning** - Section exists but may be too short or incomplete

## Output Format

### When All Validations Pass ✅

```
======================================================================
🧪 GitHub Epic & Issue Template Validator
======================================================================

📍 Repository: owner/repo

✅ GitHub authentication successful

🔍 Searching for epics in owner/repo...
Found N open epic(s)

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📌 Epic #123: Epic Title
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✅ Epic template: VALID

📋 Child Issues: 5
  ✅ #124: Child Issue 1
  ✅ #125: Child Issue 2
  ✅ #126: Child Issue 3
  ✅ #127: Child Issue 4
  ✅ #128: Child Issue 5

======================================================================
📊 VALIDATION SUMMARY
======================================================================

Epics:       1/1 valid
Child Issues: 5/5 valid

Errors:    0
Warnings:  0

======================================================================
✅ ALL VALIDATIONS PASSED - READY TO PROCEED
======================================================================

✨ All epics and child issues match template formats!

🚀 Next Steps:
   1. Run: /scope-release --current
   2. Run: /autopilot <EPIC_NUMBER> for each epic
```

Exit code: **0**

### When Validations Fail ❌

```
======================================================================
📊 VALIDATION SUMMARY
======================================================================

Epics:       0/1 valid
Child Issues: 3/5 valid

Errors:    4
Warnings:  2

======================================================================
❌ VALIDATIONS FAILED - PLEASE FIX ISSUES ABOVE
======================================================================

⚠️  4 critical error(s) must be fixed before proceeding

💡 2 warning(s) - recommended to fix

📝 To fix issues:
   1. Go to each issue URL on GitHub
   2. Edit the issue body
   3. Add missing sections
   4. Fill in all required fields
   5. Remove TBD placeholders
   6. Re-run this validation script
```

Exit code: **1**

## Common Issues and Fixes

### ❌ Missing required section: "## Overview"

**Fix:** Edit the issue on GitHub and add the missing section header and content.

```markdown
## Overview

[Add 10+ character description here]
```

### ❌ Section contains unfilled template variables or TBD placeholders

**Fix:** Replace template variables and placeholders with actual content:

```markdown
# BEFORE (error)
## Acceptance Criteria
- {{CRITERION_1}}
- {{CRITERION_2}}
- TBD

# AFTER (valid)
## Acceptance Criteria
- User can log in with email
- Password must be at least 8 characters
- Session persists for 24 hours
```

### ⚠️ No child issue links found

**Fix:** Add child issue links to epic's "Child Issues" section:

```markdown
## Child Issues

1. #124
2. #125
3. #126
```

## Exit Codes

- **0** - All validations passed, ready to proceed
- **1** - Validations failed, critical errors present
- Other - Unexpected error (check stderr output)

## Integration with Automation

After successful validation (exit code 0):

```bash
# Use in scripts to auto-proceed
if npm run validate-github-templates; then
  npm run scope-release --current
fi
```

## Troubleshooting

**Error: GitHub authentication failed**
```bash
# Set your GitHub token
export GH_TOKEN=ghp_xxxxxxxxxxxx
# Or use GITHUB_TOKEN
export GITHUB_TOKEN=ghp_xxxxxxxxxxxx

# Try again
npm run validate-github-templates
```

**Error: Failed to fetch epics from GitHub**
- Verify epics have the `epic` label on GitHub
- Check GitHub API rate limits: `curl -H "Authorization: token $GH_TOKEN" https://api.github.com/rate_limit`
- Verify repository access permissions

**Error: Could not fetch child issues**
- Child issues must reference the epic number in their body (e.g., "Epic #123")
- Not all issues referencing the epic will be returned if API rate limits are exceeded

## Next Steps After Validation

1. ✅ All validations pass →  Run `/scope-release --current`
2. ✅ Issues created in GitHub → Run `/autopilot <EPIC_NUMBER>` for each epic
3. ✅ Implementation complete → Review and merge PRs to dev/main

---

**Related Templates:**
- @epic.template.md - Epic format specification
- @enhancement.template.md - Enhancement format specification