- 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
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