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

Validate PR format, sections, and content before pushing to GitHub.

**Tier:** FREE  
**Pattern:** QUALITY (Code Review & Validation)  
**Cost:** ~5-10 tokens per validation

## What It Does

Validates pull request against format standards to catch issues before they reach GitHub:

1. **Title Format** - Checks conventional commits format
2. **Description Length** - Ensures minimum content (50+ characters)
3. **Required Sections** - Validates all sections based on PR type
4. **Checklist Completion** - Checks 50%+ completion (if present)
5. **Auto-fix** - Optionally fixes common issues automatically

## Usage

```bash
# Validate from environment variables
/validate-pr

# Validate specific PR (if on GitHub already)
/validate-pr --pr <number>

# With auto-fix enabled
/validate-pr --auto-fix

# Dry-run mode (preview without side effects)
/validate-pr --dry-run
```

**Examples:**
```bash
# Before pushing locally
export PR_TITLE="feat(auth): add login functionality"
export PR_BODY="..."
/validate-pr

# Auto-fix common issues
/validate-pr --auto-fix

# For CI/CD workflows
/validate-pr --pr 42 --strict
```

## What It Validates

### 1. Title Format (Conventional Commits)

**Valid:**
- `feat(scope): description`
- `fix(utils): handle edge case`
- `refactor(core): optimize logic`
- `docs(readme): update instructions`

**Invalid:**
- ❌ `Add login functionality` (missing type)
- ❌ `WIP: still working` (forbidden word)
- ❌ Title > 72 characters
- ❌ `feat:` (missing scope)

### 2. Description Quality

- **Minimum:** 50 characters required
- **Recommended:** 100-500 characters for context
- Shows current vs. required length

### 3. Required Sections by PR Type

**Feature PRs (feat):**
- Change Summary
- Testing Evidence
- Reviewer Focus
- Rollback Plan

**Bug Fix PRs (fix):**
- Bug Fix Summary
- Reproduction Steps
- Testing Evidence
- Verification

**Refactor PRs (refactor):**
- Refactoring Summary
- Changes Overview
- Testing Evidence
- Backward Compatibility

**Release PRs:**
- Release Summary
- Issues Resolved
- Changes Included
- Testing Evidence
- Deployment Notes

### 4. Checklist Completion

- If checklist present: 50%+ items must be checked
- If no checklist: OK (encouraged but not required)
- Validates checkbox format `- [ ]` or `- [x]`

## Workflow

### Step 1: Set Environment Variables

```bash
export PR_TITLE="feat(auth): add login functionality"
export PR_BODY="
## Summary

Added user login functionality with email/password authentication.

## Testing Evidence

- [x] Unit tests written (95% coverage)
- [x] Integration tests passing
- [x] Manual testing completed

## Reviewer Focus

- Authentication flow is critical - please review carefully
- Password hashing uses bcrypt with salt rounds = 12

## Rollback Plan

Revert the migrations and remove auth routes
"
```

### Step 2: Run Validation

```bash
/validate-pr
```

### Step 3: Review Results

```
✅ PR validation passed!

All checks passed:
✓ Title format: valid
✓ Description: 250 chars (50+ required)
✓ Required sections: all present
✓ Checklist: 2/2 items complete
```

**If issues found:**

```
⚠️  PR validation warnings:

❌ PR title exceeds 72 characters (current: 85)
❌ Missing required section: "Testing Evidence"
⚠️  Checklist only 33% complete (1/3 items checked)

💡 Tip: You can proceed despite warnings, but fixing these issues improves PR quality.
```

### Step 4: Auto-Fix (Optional)

```bash
/validate-pr --auto-fix
```

**Auto-fixes:**
- ✨ Shortens titles > 72 chars (at word boundary)
- ✨ Fixes checkbox formatting
- ✨ Adds placeholder sections
- ✨ Ensures minimum description length

**Output:**
```
🔧 Auto-fix: Shortened title from 85 to 71 chars
🔧 Auto-fix: Corrected checkbox formatting
🔧 Auto-fix: Added placeholder section "Testing Evidence"

✨ Auto-fixed issues detected. Review changes above before proceeding.
```

## Advanced Options

### Strict Mode (Blocks on Errors)

```bash
/validate-pr --strict
```

- Non-zero exit code if validation fails
- Useful for CI/CD workflows that require blocking
- Default mode is non-blocking (exit 0 unless --strict)

### GitHub Integration

```bash
# Validate a PR that's already on GitHub
/validate-pr --pr 42

# Uses: gh pr view 42 --json title,body
```

### Pre-commit Hook Setup

```bash
# Install optional pre-commit hook
/validate-pr --setup-hook

# This creates: .git/hooks/pre-commit
# Validates local commits before push
# Can be bypassed with: git commit --no-verify
```

## Configuration

**Default config location:** `.github/pr-validation-config.yml`

**Example config:**

```yaml
validation:
  minLength: 50
  strictMode: false
  
templates:
  feature:
    required:
      summary: 'Change Summary'
      testing: 'Testing Evidence'
      reviewer_focus: 'Reviewer Focus'
      rollback: 'Rollback Plan'
  
  bugfix:
    required:
      summary: 'Bug Fix Summary'
      reproduction: 'Reproduction Steps'
      testing: 'Testing Evidence'
      verification: 'Verification'
  
  refactor:
    required:
      summary: 'Refactoring Summary'
      changes: 'Changes Overview'
      testing: 'Testing Evidence'
      backward_compatibility: 'Backward Compatibility'
```

## Integration with Commands

This validation is **automatically integrated** into:

- `/implement-issue` - Before creating PR
- `/create-release-pr` - Before creating release PR
- `/implement-epic` - Before creating epic PR
- `/publish-distribution` - Before creating publish PR

You can also run manually:

```bash
# Before pushing your own branch
/validate-pr

# In CI workflows
/validate-pr --strict --pr ${{ github.event.pull_request.number }}
```

## Error Messages & Fixes

| Error | Fix |
|-------|-----|
| Title exceeds 72 chars | Use `--auto-fix` or manually shorten |
| Missing section "X" | Add `## X` header with content |
| Checklist < 50% | Complete at least half the checklist items |
| Description too short | Add more detail (50+ characters required) |
| Forbidden word "WIP" | Remove WIP/TODO/FIXME/HACK from title |
| Conventional format required | Use `type(scope): description` |

## Benefits

✅ **Early Detection** - Catch formatting issues before push  
✅ **Clear Feedback** - Specific error messages with fixes  
✅ **Auto-fix** - Optionally fix common issues automatically  
✅ **Safe** - Warnings never block (unless --strict mode)  
✅ **Lightweight** - ~5-10 tokens per validation  
✅ **CI/CD Ready** - Works in GitHub Actions or local workflows  

## Notes

- Validation is **informational by default** (non-blocking)
- Use `--strict` flag to enforce in CI workflows
- Configuration is optional (sensible defaults included)
- All output is color-coded for readability
- Works with git commit hooks for pre-commit validation