jackin-refresh-pr

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

jackin-refresh-pr

Reconcile an open PR's title and body against the current diff, so the body describes what the branch actually ships now — not what it shipped when it was opened. Run when the body has drifted: more commits landed, scope grew or shifted, the title still reads

docs:

but the PR now ships a feature.

cargo xtask pr body

with

jackin-create-pr

— the binary owns the Verify-locally block selection; the agent owns the prose. This is the deliberate, on-demand version of the reconciliation

jackin-merge-pr

runs at its step 5.

协调已打开PR的标题和正文与当前diff的一致性，让正文准确描述该分支当前实际要交付的内容——而非PR刚创建时计划交付的内容。当正文内容偏离实际情况时运行此工具：比如新增了更多提交、范围扩大或变更，标题仍显示

docs:

但PR实际包含功能代码等场景。

与

jackin-create-pr

共享

cargo xtask pr body

功能——二进制文件负责「本地验证」区块的选择；agent负责描述文字的处理。这是

jackin-merge-pr

在第5步执行的协调操作的按需触发版本。

When to use

使用场景

Operator asks to refresh / update the PR body or title ("the body is out of date", "refresh the PR").
Body has become actively misleading for a reviewer landing on it right now.

操作人员要求刷新/更新PR正文或标题（如「正文内容过时了」、「刷新PR」）。
正文内容对刚查看PR的评审人员产生误导。

When NOT to use

不适用场景

Opening a new PR →
```
jackin-create-pr
```
.
At merge-readiness →
```
jackin-merge-pr
```
step 5 reconciles as the final gate; don't double-refresh.
After every iteration commit — refresh is operator-triggered, not commit-triggered (
```
.github/AGENTS.md
```
PR-body refresh policy). Auto-refreshing churns the body and wastes attention.

创建新PR → 使用
```
jackin-create-pr
```
。
准备合并时 →
```
jackin-merge-pr
```
的第5步会将协调作为最终检查环节；无需重复刷新。
每次迭代提交后 → 刷新需由操作人员触发，而非提交触发（参考
```
.github/AGENTS.md
```
中的PR正文刷新策略）。自动刷新会导致正文频繁变更，分散注意力。

Arguments

参数

```
PR
```
— PR number (defaults to the current branch's PR).

```
PR
```
— PR编号（默认值为当前分支对应的PR）。

Process

流程

Resolve the PR.

gh pr view <PR> --json number,title,body,headRefName,baseRefName

. Hold the current title and body.

Gather the fresh shape.
```
git fetch origin <baseRefName>
```
, then
```
cargo xtask pr body --base origin/<baseRefName> > /tmp/pr-body.fresh.md
```
. Read the change digest on stderr (the rust/docs/capsule/schema categories + file list) — that is what the change is now. Read the fresh skeleton on stdout — its set of
```
### 
```
blocks under
```
## Verify locally
```
is the selection the current diff requires.
Reconcile the Verify-locally blocks. Diff the fresh skeleton's block set against the live body's:
- In the fresh selection but missing from the body → add it (structure from the template, filled for this PR).
- In the body but dropped by the fresh selection → remove it.
- In both → keep the operator's fill verbatim. The Checkout block carries the real PR number; Rust tests carry the scoped filter; User smoke carries PR-specific steps. Never overwrite a kept block with the placeholder.
Done when every
```
### 
```
block under
```
## Verify locally
```
matches the binary's selection for the current diff, and every kept block retains its authored content.
Reconcile the prose. Read
```
gh pr diff <PR>
```
and
```
git log origin/<baseRefName>..HEAD --oneline
```
. For each prose section the body carries (Summary, What ships, Behavior changes, What this addresses, Hard rule, Not included, Migration notes):
- Still matches what shipped → leave untouched. Refresh is anti-churn; do not rewrite what is right.
- Drifted → rewrite to match the current diff. Section no longer earned → drop it. New outcome shipped with no section → add it.
Done when every prose section reflects the current diff, and no section restates the diff file-by-file.
Reconcile the title. Does the Conventional Commits subject still describe the shipped scope? If the PR grew — a
```
fix(typo)
```
that now ships a feature, a
```
docs:
```
that now contains code — update type and scope via
```
gh pr edit <PR> --title
```
. Pause for confirmation only if the scope shift is meaningful enough that the operator might not have noticed (
```
.github/AGENTS.md
```
title/description rule).
Write the body. Build the reconciled body in a temp file — kept prose, rewritten prose, reconciled blocks — then
```
gh pr edit <PR> --body-file /tmp/pr-body.md
```
. Never
```
--body "..."
```
; the body-construction rule in
```
.github/AGENTS.md
```
mandates
```
--body-file
```
to survive code fences and
```
$
```
.
Verify the render.
```
gh pr view <PR> --json body -q .body
```
— confirm no stray
```
\`
```
or
```
\$
```
from hand-editing. Fix with
```
--body-file
```
if broken.
Report. Name what moved: blocks added/dropped, prose sections rewritten, the title change (old → new) and why. Do not ask permission to refresh — the operator asked. Do surface a scope-shifting title change before it sticks if the operator might disagree.

解析PR。执行

gh pr view <PR> --json number,title,body,headRefName,baseRefName

，获取当前标题和正文。

获取最新内容结构。执行
```
git fetch origin <baseRefName>
```
，然后运行
```
cargo xtask pr body --base origin/<baseRefName> > /tmp/pr-body.fresh.md
```
。读取stderr中的变更摘要（rust/docs/capsule/schema分类+文件列表）——这是当前变更的实际内容。读取stdout中的最新骨架——其
```
## Verify locally
```
下的
```
### 
```
区块集合是当前diff所需的选择内容。
协调「本地验证」区块。对比最新骨架的区块集合与现有正文的区块：
- 最新选择中有但正文缺失的区块 → 添加（使用模板结构，并针对当前PR填充内容）。
- 正文中有但最新选择已移除的区块 → 删除。
- 两者都有的区块 → 完全保留操作人员填写的内容。Checkout区块包含真实PR编号；Rust测试包含范围过滤器；用户冒烟测试包含PR特定步骤。绝不能用占位符覆盖保留的区块。
完成标志：
```
## Verify locally
```
下的每个
```
### 
```
区块都与二进制文件针对当前diff的选择一致，且所有保留的区块都保留其编辑后的内容。
协调描述文字。读取
```
gh pr diff <PR>
```
和
```
git log origin/<baseRefName>..HEAD --oneline
```
的输出。针对正文包含的每个描述章节（Summary、What ships、Behavior changes、What this addresses、Hard rule、Not included、Migration notes）：
- 仍与实际交付内容匹配 → 保持不变。刷新的目的是减少不必要变更；不要重写正确的内容。
- 已偏离实际 → 重写以匹配当前diff。章节不再符合实际内容 → 删除。新增了未对应章节的交付内容 → 添加对应章节。
完成标志：每个描述章节都反映当前diff的内容，且没有章节逐文件重复diff内容。
协调标题。Conventional Commits格式的主题是否仍能描述当前交付范围？如果PR范围扩大——比如原本是
```
fix(typo)
```
现在包含功能代码，原本是
```
docs:
```
现在包含代码——则通过
```
gh pr edit <PR> --title
```
更新类型和范围。仅当范围变更足够大，操作人员可能未注意到时，才暂停等待确认（参考
```
.github/AGENTS.md
```
中的标题/描述规则）。
写入正文。在临时文件中构建协调后的正文——保留的描述文字、重写的描述文字、协调后的区块——然后执行
```
gh pr edit <PR> --body-file /tmp/pr-body.md
```
。绝不要使用
```
--body "..."
```
；
```
.github/AGENTS.md
```
中的正文构建规则要求使用
```
--body-file
```
，以避免代码围栏和
```
$
```
符号出现问题。
验证渲染效果。执行
```
gh pr view <PR> --json body -q .body
```
——确认没有手动编辑导致的多余
```
\`
```
或
```
\$
```
符号。如果有问题，使用
```
--body-file
```
修复。
报告结果：说明变更内容：添加/删除的区块、重写的描述章节、标题变更（旧→新）及原因。无需请求刷新权限——操作人员已提出要求。但若标题变更涉及范围调整，且操作人员可能有异议，则需在生效前告知。

Common mistakes

常见错误

Regenerating the body from the skeleton and losing the operator's prose — the skeleton carries placeholders; refresh preserves authored content and only rewrites what drifted.
Rewriting prose that was already accurate — churns the diff and wastes attention.
Hand-selecting Verify-locally blocks instead of
```
cargo xtask pr body
```
— the binary is the selection oracle.
Using
```
gh pr edit --body "..."
```
instead of
```
--body-file
```
— breaks on code fences and
```
$
```
.
Forgetting the render check — a broken
```
\`
```
or
```
\$
```
ships silently.
Refreshing after every commit — violates the operator-triggered policy.

从骨架重新生成正文并丢失操作人员编写的描述文字——骨架仅包含占位符；刷新操作应保留已编辑内容，仅重写偏离实际的部分。
重写已经准确的描述文字——会导致diff频繁变更，分散注意力。
手动选择「本地验证」区块而非使用
```
cargo xtask pr body
```
——二进制文件是区块选择的权威来源。
使用
```
gh pr edit --body "..."
```
而非
```
--body-file
```
——会破坏代码围栏和
```
$
```
符号。
忘记验证渲染效果——损坏的
```
\`
```
或
```
\$
```
会被静默提交。
每次提交后都刷新——违反了操作人员触发的策略。

Tooling

工具说明

cargo xtask pr body --base origin/<base>

(jackin❯ repo) emits the change digest to stderr and the Verify-locally-block-filtered skeleton to stdout. Shared with

jackin-create-pr

. The binary owns block selection; the agent owns prose reconciliation. No xtask subcommand refreshes a PR — this skill orchestrates

pr body

(selection) +

gh pr edit

(write).

cargo xtask pr body --base origin/<base>

（jackin❯仓库）将变更摘要输出到stderr，将过滤后的「本地验证」区块骨架输出到stdout。与

jackin-create-pr

共享此功能。二进制文件负责区块选择；agent负责描述文字的协调。没有xtask子命令可以直接刷新PR——此skill负责编排

pr body

（选择）和

gh pr edit

（写入）操作。