pr-validate

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

PR Validate Skill

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

针对PR的专项验证，确保代码变更清晰、聚焦且就绪。

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

通过检查隔离性、上游分支对齐、范围控制和质量关卡，验证PR分支是否可提交。

输入：分支名称（默认：当前分支）

适用场景：

执行
```
$pr-prep
```
之前
```
$pr-implement
```
完成之后
怀疑存在范围蔓延时

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

1.  分支识别     -> 确定目标分支及上游分支
2.  上游分支对齐   -> 首要检查：变基状态（阻塞项）
3.  CONTRIBUTING.md      -> 验证合规性（阻塞项）
4.  隔离性检查      -> 单一类型、主题统一的文件
5.  范围检查          -> 验证变更与预期范围匹配
6.  质量关卡         -> 测试、代码检查（非阻塞项）
7.  报告生成    -> 生成包含通过/失败结果的汇总报告

Phase 2: Upstream Alignment (BLOCKING - CHECK FIRST)

阶段2：上游分支对齐（阻塞项 - 优先检查）

bash

undefined

bash

undefined

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 |

---

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


| 检查项 | 通过标准 |
|-------|----------|
| 最小差异 | 落后上游分支少于20个提交 |
| 无冲突 | 合并/变基可成功执行 |

---

Phase 4: Isolation Check (BLOCKING)

阶段4：隔离性检查（阻塞项）

bash

undefined

bash

undefined

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 |

---

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


| 检查项 | 通过标准 |
|-------|----------|
| **单一提交类型** | 所有提交使用相同前缀 |
| **主题统一文件** | 所有变更文件与PR范围相关 |
| **原子化范围** | 可用一句话说明变更内容 |

---

Phase 5: Scope Check

阶段5：范围检查

bash

undefined

bash

undefined

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"

---

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

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.

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

混合提交类型

bash

undefined

bash

undefined

Cherry-pick to clean branch

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

undefined

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

undefined

Upstream Divergence

上游分支差异过大

bash

undefined

bash

undefined

Rebase on latest upstream

git fetch origin main git rebase origin/main

---

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

不要做	正确做法
分析过时分支	优先检查上游分支
跳过验证	在执行$pr-prep之前运行验证
忽略范围蔓延	提取无关变更到单独分支
混合修复与重构	按类型拆分PR

Examples

示例

Validate PR Before Submission

提交前验证PR

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.

用户指令："Validate this PR branch for isolation and scope creep."

执行流程：

检查上游分支对齐情况及分支新鲜度。
检测范围蔓延及无关文件变更。
输出修复步骤及通过/失败状态。

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.

用户指令："Run PR validation before I run

$pr-prep

执行流程：

执行隔离性和范围检查。
确认质量关卡就绪状态。
返回是否可以继续的建议。

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

问题	原因	解决方案
验证报告显示分支过时	上游分支已更新	基于上游分支变基/合并后重新运行验证
检测到范围蔓延	存在额外文件或混合目标	将无关变更拆分到后续PR中
对齐检查失败	分支与目标预期差异过大	协调基准分支与验收标准
输出内容不清晰	未对检查结果排序	按阻塞项/非阻塞项的严重程度对结果排序