open-pr

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Open PR

打开PR

Create or update a GitHub pull request from the template below, written with

writing-lean

使用以下模板创建或更新GitHub pull request，遵循

writing-lean

写作规范。

Step 1: Check for Existing PR

步骤1：检查是否已有PR

Check if a PR already exists for the current branch:

bash

gh pr view --json number,title,body,url

If PR exists: proceed to update flow (Step 5b)
If no PR exists: proceed to create flow (Step 5a)

检查当前分支是否已存在PR：

bash

gh pr view --json number,title,body,url

若PR已存在：进入更新流程（步骤5b）
若PR不存在：进入创建流程（步骤5a）

Step 1b (Required): Identify the correct diff base

步骤1b（必填）：确定正确的diff基准分支

Never assume
main
. You must diff against the actual base branch.

If updating an existing PR, use the PR base:

bash

gh pr view --json baseRefName,headRefName
git fetch origin --prune
git diff --stat "origin/<baseRefName>...HEAD"

If creating a new PR (no PR exists yet), use the repo default branch:

bash

git fetch origin --prune
git symbolic-ref refs/remotes/origin/HEAD
git diff --stat "origin/<defaultBranch>...HEAD"

绝对不要默认是
main
分支。必须基于实际的基准分支进行diff对比。

若更新现有PR，使用该PR的基准分支：

bash

gh pr view --json baseRefName,headRefName
git fetch origin --prune
git diff --stat "origin/<baseRefName>...HEAD"

若创建新PR（尚不存在PR），使用仓库的默认分支：

bash

git fetch origin --prune
git symbolic-ref refs/remotes/origin/HEAD
git diff --stat "origin/<defaultBranch>...HEAD"

Step 2: Fetch the GitHub Issue

步骤2：获取GitHub Issue

Parse the issue number from the branch name. Branch names follow the pattern

{issue_number}-{description}

(e.g.,

54-return-to-after-login

-> issue #54).

A number alone does not identify an issue. Issue numbers are per-repository, and the issue is not always in the repo you are opening the PR from — a change in one repo often implements an issue tracked in another. Resolve the repo before fetching, defaulting to the current one:

bash

undefined

从分支名中解析issue编号。分支名遵循

{issue_number}-{description}

格式（例如，

54-return-to-after-login

对应issue #54）。

仅凭数字无法确定唯一的issue。 Issue编号是仓库级的，且issue不一定位于你提交PR的仓库中——一个仓库的变更通常对应另一个仓库中跟踪的issue。获取issue前先确认所在仓库，默认使用当前仓库：

bash

undefined

Get current branch name

git branch --show-current

Default to this repo; override when the issue lives elsewhere

ISSUE_REPO="$(gh repo view --json nameWithOwner --jq .nameWithOwner)"

Fetch issue details

gh issue view <issue_number> --repo "$ISSUE_REPO" --json title,body,url


If the fetched issue doesn't match the work in the diff, you have resolved the wrong repo — ask
rather than writing a PR body against someone else's issue.

Extract the issue title and body for context.

gh issue view <issue_number> --repo "$ISSUE_REPO" --json title,body,url


如果获取到的issue与diff中的工作内容不匹配，说明你找错了仓库——应当询问用户，而不是针对他人的issue编写PR正文。

提取issue的标题和正文作为上下文参考。

Step 3: Analyze Git Changes

步骤3：分析Git变更

Run these commands to understand the scope of changes:

bash

undefined

运行以下命令了解变更范围：

bash

undefined

Check for uncommitted changes (warn user if any)

git status

Get all commits on this branch (against the actual base branch)

git log <base>...HEAD --oneline

Get the full diff summary against the actual base branch

git diff --stat <base>...HEAD

REQUIRED: Inspect the actual line changes (not just stats)

git diff <base>...HEAD


**Required rule:** Before writing/updating the PR body, you must read the diff and extract
**1-3 concrete line-level changes** (e.g., a rename `OldName` -> `NewName`, a new env var key, an endpoint path change).
No speculative bullets.

git diff <base>...HEAD


**必填规则：** 在编写/更新PR正文前，必须阅读diff并提取**1-3项具体的行级变更**（例如，重命名`OldName`为`NewName`、新增环境变量键、端点路径变更）。不得添加推测性的条目。

Step 3b: Check the size against the ceiling

步骤3b：检查变更规模是否超出上限

bash

git diff --shortstat <base>...HEAD

Discount lockfiles, snapshots and generated files, then compare what's left against the changed-line ceiling in Decomposing work before Ready for Agent in the

issue-tracker

skill. That skill holds the number; don't restate it here, or there are two copies to keep in step.

If the diff is over, say so and propose, in this order:

Simplify. Cut documentation that fails the
```
writing-lean
```
deletion test first, then anything else the change doesn't need. Most oversized diffs shrink here.
Split. Only once it's as small as it's going to get: cut sub-issues, set the leaves to
```
Ready for Agent
```
, and open this pull request for the slice that's finished — stacking it on the previous slice where they depend on each other.

This never blocks. It's a prompt to reconsider at the last moment before a reviewer sees the diff, not a gate. If the author says ship it, ship it.

bash

git diff --shortstat <base>...HEAD

排除lockfile、快照和生成的文件后，将剩余变更行数与

issue-tracker

技能中Ready for Agent前的工作拆解部分规定的变更行上限进行对比。上限数值以该技能中的定义为准，此处不再重复，避免两处内容需要同步维护。

如果diff超出上限，告知用户并按以下顺序提出建议：

简化。 首先删除未通过
```
writing-lean
```
删减测试的文档，再移除其他变更不需要的内容。大多数超规模的diff都能在这里缩减下来。
拆分。 只有当diff已经无法再缩小时才进行拆分：拆解出子issue，将叶子节点设为
```
Ready for Agent
```
，并为已完成的部分创建PR——如果存在依赖关系，将其堆叠在前一个分片PR之上。

这一步不会阻塞流程。 这只是在评审人员看到diff前的最后一刻提醒你重新考量，而非硬性门槛。如果作者确认没问题，就直接提交。

Step 4: Generate PR Content

步骤4：生成PR内容

Title format:

{issue_number}: {issue_title}

Example:

54: Return to after login

Body template:

markdown

undefined

标题格式：

{issue_number}: {issue_title}

示例：

54: Return to after login

正文模板：

markdown

undefined

Description

1-2 bullets: what and why

1-2 bullets: what and why

Changes

2-5 bullets max: user-visible or behavior changes

2-5 bullets max: user-visible or behavior changes

How to Test

2-4 steps max
Include the single most important edge case

2-4 steps max
Include the single most important edge case

Deployment Notes

OPTIONAL: Only include if there are special deployment steps or risks to call out
Flag any tasks that must be done before or after merging (e.g., "Add env var X before merging", "Run data migration Y after merging", "Add a variable to 1Password")

OPTIONAL: Only include if there are special deployment steps or risks to call out
Flag any tasks that must be done before or after merging (e.g., "Add env var X before merging", "Run data migration Y after merging", "Add a variable to 1Password")

Related Issues

Closes #<issue_number>


**Qualify the reference when the issue is in another repo** — `Closes owner/repo#N`. The qualified
form does close the issue on merge, the same as a same-repo reference; a bare `#N` silently means
this repo's issue N, which is a different issue or none at all.

Closes #<issue_number>


**如果issue位于其他仓库，必须使用完整引用格式** —— `Closes owner/repo#N`。完整引用格式在PR合并时会自动关闭对应issue，和同仓库引用的效果一致；而仅写`#N`会默认指向当前仓库的第N号issue，可能对应完全不同的issue，甚至不存在。

Step 5a: Create New PR

步骤5a：创建新PR

Push the branch and open the PR ready for review:

bash

undefined

推送分支并创建可供评审的PR：

bash

undefined

Push branch to remote

git push -u origin HEAD

Create the PR, against the base resolved in Step 1b

gh pr create --base "<base>" --title "<issue_number>: <issue_title>" --body "$(cat <<'EOF'

Description

<1-2 bullets: what/why>

<1-2 bullets: what/why>

Changes

<2-5 bullets max>

<2-5 bullets max>

How to Test

<2-4 steps max>

<2-4 steps max>

Deployment Notes

OPTIONAL: delete this section entirely if there are no special steps or risks
Flag any tasks that must be done before or after merging

OPTIONAL: delete this section entirely if there are no special steps or risks
Flag any tasks that must be done before or after merging

Related Issues

Closes #<issue_number> EOF )"

Ask a human to look at it

gh pr edit --add-reviewer <maintainer>


**`--base` is not optional.** Without it `gh` targets the repo's default branch, so a slice
stacked on a previous one would show its parent's changes in the diff too — the opposite of the
clean review Step 3b's stacking advice is trying to produce.

gh pr edit --add-reviewer <maintainer>


**`--base`参数不是可选的。** 如果不加该参数，`gh`会默认指向仓库的默认分支，这样堆叠在前一个PR上的分片PR的diff中会包含父PR的变更——这与步骤3b中堆叠建议想要实现的清晰评审效果完全相反。

Step 5b: Update Existing PR

步骤5b：更新现有PR

Push latest changes and update the PR description:

bash

undefined

推送最新变更并更新PR描述：

bash

undefined

Push latest changes

git push

Update PR body

gh pr edit --body "$(cat <<'EOF'

Description

<1-2 bullets: what/why>

<1-2 bullets: what/why>

Changes

<2-5 bullets max>

<2-5 bullets max>

How to Test

<2-4 steps max>

<2-4 steps max>

Deployment Notes

OPTIONAL: Only include if there are special deployment steps or risks to call out. If there are none, delete this section entirely.
Flag any tasks that must be done before or after merging (e.g., "Add env var X before merging", "Run data migration Y after merging", "Add a variable to 1Password")

OPTIONAL: Only include if there are special deployment steps or risks to call out. If there are none, delete this section entirely.
Flag any tasks that must be done before or after merging (e.g., "Add env var X before merging", "Run data migration Y after merging", "Add a variable to 1Password")

Related Issues

Closes #<issue_number> EOF )"


Optionally update the title if needed:

```bash
gh pr edit --title "<issue_number>: <issue_title>"

Closes #<issue_number> EOF )"


如有需要，可选择性更新标题：

```bash
gh pr edit --title "<issue_number>: <issue_title>"

Notes

注意事项

Open ready for review, and request one. Draft is not the default — it means the run stopped short. Reserve it for the Blocked and Error endings in How a run ends in the repo's
```
AGENTS.md
```
, where the PR carries a comment explaining what is needed. A Complete run opens the PR ready and asks a human to look at it
When updating, replace stale bullets rather than appending to them

创建PR时直接设为可评审状态，并发起评审请求。 Draft（草稿）不是默认状态——它代表运行中途终止。仅在仓库
```
AGENTS.md
```
中运行结束方式章节定义的**Blocked（阻塞）和Error（错误）**结束场景下使用草稿状态，此时PR需附带评论说明所需支持。**Complete（完成）**状态的运行会创建可评审的PR并请求人工审核。
更新PR时，应替换过时的条目，而非直接追加。