piv-create-pr

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Create PR: Open the Pull Request, Hand Off for Review

创建PR：打开拉取请求，移交评审

This is the ship step of the PIV loop: the implementation is committed on a feature branch; now open the PR so it can be reviewed (by the

piv-review-pr

agentic gate, then a human).

这是PIV循环中的交付步骤：代码实现已提交到功能分支；现在打开PR，以便进行评审（先由

piv-review-pr

智能网关评审，再由人工评审）。

Phase 0 — Detect the base branch

阶段0——检测基础分支

Don't hardcode

main

. Resolve it:

If
```
$ARGUMENTS
```
contains
```
--base <branch>
```
, use that.

Else:

git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@'

Fallback:

git remote show origin 2>/dev/null | grep 'HEAD branch' | awk '{print $NF}'

Last resort:
```
main
```
. Store as
```
{base}
```
.

不要硬编码

main

分支。按以下逻辑解析：

如果
```
$ARGUMENTS
```
包含
```
--base <branch>
```
，则使用该分支。

否则：

git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@'

备选方案：

git remote show origin 2>/dev/null | grep 'HEAD branch' | awk '{print $NF}'

最终 fallback：
```
main
```
。将结果存储为
```
{base}
```
。

Phase 1 — Validate git state

阶段1——验证Git状态

bash

git branch --show-current
git status --short
git log origin/{base}..HEAD --oneline

State	Action
On `{base}`	STOP: "Create a feature branch first (the ticket should be on its own branch)."
Uncommitted changes	STOP: "Commit (or stash) before opening the PR."
No commits ahead of `{base}`	STOP: "Nothing to PR."
Existing PR for this branch ( `gh pr list --head $(git branch --show-current) --json url` )	STOP and print the URL.
Clean, commits ahead, no PR	PROCEED

bash

git branch --show-current
git status --short
git log origin/{base}..HEAD --oneline

状态	操作
当前处于 `{base}` 分支	终止："请先创建功能分支（工单应在专属分支上开发）。"
存在未提交的变更	终止："打开PR前请提交（或暂存）变更。"
没有比 `{base}` 分支超前的提交	终止："没有内容可提交PR。"
该分支已有对应的PR（ `gh pr list --head $(git branch --show-current) --json url` ）	终止并打印该PR的URL。
状态干净、有超前提交且无现有PR	继续执行

Phase 2 — Gather context for the body

阶段2——收集PR正文的上下文信息

Project conventions: if
```
.claude/references/conventions.md
```
exists, read its
```
## pr
```
section — its rules win over the default template below (sections, tone, what must be stated). That file is where a project's specifics live; this skill stays general.

Commits:

git log origin/{base}..HEAD --pretty=format:"- %s"

Files:
```
git diff --stat origin/{base}..HEAD
```
Implementation report (if
```
piv-implement
```
wrote one —
```
.claude/reports/<…>-report.md
```
): pull the summary, validation results, and documented deviations (these belong in the PR body — they tell the reviewer what was intentional).
Linked ticket / issue: look for
```
ACC-…
```
,
```
#123
```
,
```
Fixes #…
```
in the commits/branch name.
PR template: if
```
.github/PULL_REQUEST_TEMPLATE.md
```
exists, fill it; else use the default below.

项目约定：如果
```
.claude/references/conventions.md
```
文件存在，读取其
```
## pr
```
章节内容——其中的规则优先级高于下方的默认模板（包括章节结构、语气、必填内容）。该文件用于存储项目的特定规则；本技能保持通用性。

提交记录：

git log origin/{base}..HEAD --pretty=format:"- %s"

文件变更：
```
git diff --stat origin/{base}..HEAD
```
实现报告（如果
```
piv-implement
```
生成过报告——
```
.claude/reports/<…>-report.md
```
）：提取摘要、验证结果以及已记录的偏差（这些内容应放入PR正文中，告知评审人员哪些是有意做出的决策）。
关联工单/问题：在提交记录或分支名称中查找
```
ACC-…
```
、
```
#123
```
、
```
Fixes #…
```
等标识。
PR模板：如果
```
.github/PULL_REQUEST_TEMPLATE.md
```
存在，使用该模板填充内容；否则使用下方的默认模板。

Phase 3 — Push and open the PR

阶段3——推送代码并打开PR

bash

git push -u origin HEAD

bash

gh pr create --base "{base}" --title "{type}: {concise description}" --body "$(cat <<'EOF'

bash

git push -u origin HEAD

bash

gh pr create --base "{base}" --title "{type}: {concise description}" --body "$(cat <<'EOF'

Summary

摘要

{1-2 sentences: what this ticket delivers}

{1-2句话：本工单实现的内容}

What changed

变更内容

{commit summaries}

{提交记录摘要}

Validation

验证情况

Tests / type-check / lint: {pass/fail from the implementation report or a fresh run}
Manual check: {what was exercised, or "pending review"}

测试/类型检查/代码扫描：{来自实现报告或最新运行结果的通过/失败状态}
人工检查：{已验证的内容，或"待评审"}

Notes for the reviewer

评审注意事项

{documented deviations from the plan — intentional decisions — or "none"}

{与计划存在的已记录偏差——有意做出的决策——或"无"}

Linked

关联内容

{ticket / issue refs, or "none"}

Ready for review. EOF )"


(`{type}` = feat/fix/refactor/… from the work. Use `--draft` if the work isn't ready for a real review.)

{工单/问题引用，或"无"}

已准备好评审。 EOF )"


（`{type}` = 本次工作的类型：feat/fix/refactor/…。如果工作尚未准备好正式评审，使用`--draft`参数标记为草稿PR。）

Output

输出结果

bash

gh pr view --json number,url,title,baseRefName,headRefName

Report the PR number + URL, the base ← head branches, and "Ready for review → run
piv-review-pr <number>
, then a human approves." This is the handoff point: the agent's loop ends at an open PR; review and merge are the gates.

bash

gh pr view --json number,url,title,baseRefName,headRefName

报告PR编号+URL、基础分支←头部分支，并提示**"已准备好评审 → 运行

piv-review-pr <number>

，随后由人工审批。"** 这是移交节点：智能体的循环在PR打开时结束；评审和合并是后续的环节。

Notes

注意事项

Tool-agnostic in spirit: this skill uses GitHub (
```
gh
```
); the same motion is "open a merge request" on GitLab, or "mark ready for review" wherever your team works. Solo with no remote? Skip the PR — commit on
```
{base}
```
and review your own diff before moving on.
Sets up parallel work: one branch per ticket → one PR per ticket is exactly what makes worktree parallelism (running independent tickets at once) clean.

本质上与工具无关：本技能使用GitHub的
```
gh
```
命令；在GitLab上对应的操作是"打开合并请求"，或在团队使用的其他平台上"标记为待评审"。如果是单人开发且无远程仓库？跳过PR环节——直接提交到
```
{base}
```
分支，在继续下一步前自行评审代码差异。
支持并行工作：一个工单对应一个分支→一个工单对应一个PR，这正是让工作树并行（同时处理独立工单）保持整洁的关键。