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-implementcompletes - 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/failPhase 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-prepFail 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/mainAnti-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 |