pr-validate

SKILL.md

PR Validate Skill

PR-specific validation that ensures changes are clean, focused, and ready.

Overview

Validates a PR branch for submission readiness by checking isolation, upstream
alignment, scope containment, and quality gates.

Input: Branch name (default: current branch)

When to Use:

Before running $pr-prep

After $pr-implement completes

When suspicious of scope creep

Workflow
1.  Branch Discovery     -> Identify branch and upstream
2.  Upstream Alignment   -> FIRST: Check rebase status (BLOCKING)
3.  CONTRIBUTING.md      -> Verify compliance (BLOCKING)
4.  Isolation Check      -> Single type, thematic files
5.  Scope Check          -> Verify changes match intended scope
6.  Quality Gate         -> Tests, linting (non-blocking)
7.  Report Generation    -> Summary with pass/fail

Phase 2: Upstream Alignment (BLOCKING - CHECK FIRST)

# Fetch latest upstream
git fetch origin main

# How many commits behind?
BEHIND=$(git rev-list --count HEAD..origin/main)
echo "Behind upstream: $BEHIND commits"

Check
Pass Criteria

Minimal divergence
< 20 commits behind

No conflicts
Merge/rebase would succeed

Phase 4: Isolation Check (BLOCKING)

# Commit type analysis
git log --oneline main..HEAD | sed 's/^[^ ]* //' | grep -oE '^[a-z]+(\([^)]+\))?:' | sort -u

# File theme analysis
git diff --name-only main..HEAD | cut -d'/' -f1-2 | sort -u

Check
Pass Criteria

Single commit type
All commits share same prefix

Thematic files
All changed files relate to PR scope

Atomic scope
Can explain in one sentence

Phase 5: Scope Check

# Infer scope from commit messages
SCOPE=$(git log --format="%s" main..HEAD | grep -oE '\([^)]+\)' | sort -u | head -1)

# All files should be within expected scope
git diff --name-only main..HEAD | grep -v "$SCOPE"

Report Generation

Pass Output

PR Validation: PASS

Branch: feature/suggest-validation (5 commits)
Upstream: main (in sync)

Checks:
  [OK] Isolation: Single type (refactor)
  [OK] Upstream: 0 commits behind
  [OK] Scope: 100% in internal/suggest/
  [OK] Quality: Tests pass

Ready for $pr-prep

Fail Output

PR Validation: BLOCKED

Checks:
  [FAIL] Isolation: Mixed types (refactor, fix, docs)
  [WARN] Upstream: 15 commits behind

Resolutions:
1. ISOLATION: Split branch by commit type
   git checkout main && git checkout -b refactor/suggest
   git cherry-pick <refactor-commits>

Run $pr-validate again after resolution.

Resolution Actions

Mixed Commit Types

# Cherry-pick to clean branch
git checkout main
git checkout -b ${BRANCH}-clean
git cherry-pick <relevant-commits-only>

Upstream Divergence

# Rebase on latest upstream
git fetch origin main
git rebase origin/main

Anti-Patterns

DON'T
DO INSTEAD

Analyze stale branch
Check upstream FIRST

Skip validation
Run before $pr-prep

Ignore scope creep
Extract unrelated changes

Mix fix and refactor
Separate PRs by type

Examples

Validate PR Before Submission

User says: "Validate this PR branch for isolation and scope creep."

What happens:

Check upstream alignment and branch freshness.

Detect scope creep and unrelated file changes.

Output remediation steps and pass/fail status.

Pre-Prep Gate

User says: "Run PR validation before I run $pr-prep."

What happens:

Execute isolation and scope checks.

Confirm quality gate readiness.

Return a go/no-go recommendation.

Troubleshooting

Problem
Cause
Solution

Validation reports stale branch
Upstream advanced
Rebase/merge from upstream then rerun

Scope creep detected
Extra files or mixed objectives
Split unrelated changes into follow-up PR

Alignment check fails
Branch diverged from target expectations
Reconcile base branch and acceptance criteria

Output unclear
Findings not prioritized
Sort findings by blocker vs non-blocker severity