pr-prep

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

PR Preparation Skill

PR准备技能

Systematic PR preparation that validates tests and generates high-quality PR bodies.

系统化的PR准备流程，可验证测试并生成高质量的PR正文。

Overview

概述

Prepares contributions by analyzing the target repo's conventions, git history, test coverage, and generating properly-formatted PR bodies.

When to Use:

Preparing a PR for an external repository
Contributing bug fixes or features

When NOT to Use:

Internal commits (use normal git workflow)
PRs to your own repositories

通过分析目标仓库的约定、Git历史、测试覆盖率，生成格式规范的PR正文，为代码贡献做准备。

适用场景:

为外部仓库准备PR
提交bug修复或功能新增

不适用场景:

内部提交（使用常规Git工作流）
向自己的仓库提交PR

Workflow

工作流

-1. Prior Work Check     -> BLOCKING: Final check for competing PRs
0.  Isolation Check      -> BLOCK if PR mixes unrelated changes
1.  Context Discovery    -> Understand target repo conventions
2.  Git Archaeology      -> Analyze commit patterns, PR history
3.  Pre-Flight Checks    -> Run tests, linting, build
4.  Change Analysis      -> Summarize what changed and why
5.  PR Body Generation   -> Create structured PR description
6.  USER REVIEW GATE     -> STOP. User must approve before submission.
7.  Submission           -> Only after explicit user approval

-1. 前期工作检查     -> 阻塞型：最终检查是否存在竞争PR
0.  独立性检查      -> 若PR混合不相关更改则阻塞
1.  上下文探索    -> 了解目标仓库约定
2.  Git溯源      -> 分析提交模式、PR历史
3.  预提交检查    -> 运行测试、代码检查、构建
4.  变更分析      -> 总结变更内容及原因
5.  PR正文生成   -> 创建结构化的PR描述
6.  用户审核环节     -> 停止。提交前必须获得用户批准。
7.  提交           -> 仅在获得用户明确批准后执行

Phase 0: Isolation Check (BLOCKING)

阶段0：独立性检查（阻塞型）

CRITICAL: Run this FIRST. Do not proceed if PR mixes unrelated changes.

关键提示：首先运行此检查。如果PR混合了不相关的更改，请勿继续。

Commit Type Analysis

提交类型分析

bash

undefined

bash

undefined

Extract commit type prefixes from branch

从分支中提取提交类型前缀

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


**Rule**: If more than one commit type prefix exists, the PR is mixing concerns.

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


**规则**：如果存在一种以上的提交类型前缀，说明该PR混合了不同关注点的内容。

File Theme Analysis

文件主题分析

bash

undefined

bash

undefined

List all files changed vs main

列出与main分支相比所有变更的文件

git diff --name-only main..HEAD

Group by directory

按目录分组

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

undefined

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

undefined

Isolation Checklist

独立性检查清单

Check	Pass Criteria
Single commit type	All commits share same prefix
Thematic files	All changed files relate to PR scope
No main overlap	Changes not already merged
Atomic scope	Can explain in one sentence

DO NOT PROCEED IF ISOLATION CHECK FAILS.

检查项	通过标准
单一提交类型	所有提交使用相同前缀
主题一致的文件	所有变更文件与PR范围相关
无main分支重复	变更内容未被合并
原子化范围	可用一句话说明

如果独立性检查不通过，请勿继续。

CRITICAL: User Review Gate

关键提示：用户审核环节

NEVER submit a PR without explicit user approval.

After generating the PR body (Phase 5), ALWAYS:

Write the PR body to a file for review
Show the user what will be submitted
STOP and ask: "Ready to submit? Review the PR body above."
Wait for explicit approval before running
```
gh pr create
```

bash

undefined

未经用户明确批准，绝不要提交PR。

生成PR正文后（阶段5），请务必：

将PR正文写入文件供审核
向用户展示即将提交的内容
暂停并询问：“是否准备提交？请审核上方的PR正文。”
在运行
```
gh pr create
```
前等待用户明确批准

bash

undefined

Write PR body to file

将PR正文写入文件

cat > /tmp/pr-body.md << 'EOF' <generated PR body> EOF

Show user

展示给用户

cat /tmp/pr-body.md

ASK - do not proceed without answer

询问 - 未得到答复请勿继续

echo "Review complete. Submit this PR? [y/N]"

---

echo "审核完成。是否提交此PR？ [y/N]"

---

Phase 3: Pre-Flight Checks

阶段3：预提交检查

bash

undefined

bash

undefined

Go projects

Go项目

go build ./... go vet ./... go test ./... -v -count=1

Node projects

Node项目

npm run build npm test

Python projects

Python项目

pytest -v

undefined

pytest -v

undefined

Pre-Flight Checklist

预提交检查清单

Phase 5: PR Body Generation

阶段5：PR正文生成

Standard Format

标准格式

markdown

undefined

markdown

undefined

Summary

摘要

Brief description of WHAT changed and WHY. 1-3 sentences. Start with action verb (Add, Fix, Update, Refactor).

简要说明变更内容及原因，1-3句话。以动作动词开头（新增、修复、更新、重构）。

Changes

变更详情

Technical details of what was modified.

修改内容的技术细节。

Test plan

测试计划

```
go build ./...
```
passes
```
go test ./...
```
passes
Manual: <specific scenario tested>

Fixes #NNN


**Key conventions:**
- Test plan items are **checked** `[x]` (you ran them before PR)
- `Fixes #NNN` goes at the end

---

```
go build ./...
```
执行通过
```
go test ./...
```
执行通过
手动测试：<具体测试场景>

Fixes #NNN


**核心约定**:
- 测试计划项需标记为**已完成** `[x]`（PR前已执行）
- `Fixes #NNN` 放在末尾

---

Phase 7: Submission (After Approval Only)

阶段7：提交（仅在批准后执行）

bash

undefined

bash

undefined

Create PR with reviewed body

使用审核后的正文创建PR

gh pr create --title "type(scope): brief description"
--body "$(cat /tmp/pr-body.md)"
--base main


**Remember**: This command should ONLY run after user explicitly approves.

---

gh pr create --title "type(scope): brief description"
--body "$(cat /tmp/pr-body.md)"
--base main


**注意**：仅在用户明确批准后执行此命令。

---

Anti-Patterns

反模式

DON'T	DO INSTEAD
Submit without approval	ALWAYS stop for user review
Skip isolation check	Run Phase 0 FIRST
Bundle lint fixes into feature PRs	Lint fixes get their own PR
Giant PRs	Split into logical chunks
Vague PR body	Detailed summary with context
Skip pre-flight	Always run tests locally

错误做法	正确做法
未经批准提交	始终暂停等待用户审核
跳过独立性检查	首先运行阶段0检查
将代码检查修复与功能PR捆绑	代码检查修复单独提交PR
大型PR	拆分为逻辑独立的小块
PR正文模糊	提供包含上下文的详细摘要
跳过预提交检查	始终在本地运行测试

Examples

示例

Prepare External PR Body

准备外部PR正文

User says: "Prepare this branch for PR submission."

What happens:

Run isolation and pre-flight validation.
Build structured PR body with summary and test plan.
Pause for mandatory user review before submit.

用户指令："为提交PR准备此分支。"

执行流程:

运行独立性和预提交验证。
生成包含摘要和测试计划的结构化PR正文。
在提交前暂停，等待强制用户审核。

Evidence-First PR Packaging

基于证据的PR打包

User says: "Generate a high-quality PR description with clear verification steps."

What happens:

Gather git archaeology and test evidence.
Synthesize concise rationale and change list.
Produce submit-ready body pending approval.

用户指令："生成高质量的PR描述，包含清晰的验证步骤。"

执行流程:

收集Git溯源和测试证据。
提炼简洁的理由和变更列表。
生成待提交的PR正文，等待批准。

Troubleshooting

故障排除

Problem	Cause	Solution
PR body is weak	Missing context from commits/tests	Re-run evidence collection and expand summary
Submission blocked	Mandatory review gate not passed	Get explicit user approval before `gh pr create`
Test plan incomplete	Commands/results not captured	Add executed checks and outcomes explicitly
Title/body mismatch	Scope drift during edits	Regenerate from latest branch diff and constraints

问题	原因	解决方案
PR正文质量差	缺少提交/测试的上下文	重新收集证据并扩展摘要
提交被阻塞	未通过强制审核环节	在执行 `gh pr create` 前获得用户明确批准
测试计划不完整	未记录命令/结果	明确添加已执行的检查及结果
标题与正文不匹配	编辑过程中范围偏离	根据最新分支差异和约束重新生成