review-anvil-improve-pr

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

review-anvil-improve-pr

Productive counterpart to

review-anvil-pr

. Where

review-anvil-pr

is read-only and posts a review comment, this preset actually modifies the code: it announces itself on the PR up front, runs the review loop with

commit_mode=per_fix

, applies fix commits to the local branch across requested rounds plus any adaptive continuation, pushes the result back to update the PR, then edits the starting comment in-place with the synthesized report (or a failure summary) — one comment in the PR timeline, two states.

review-anvil-pr

的实用配套工具。

review-anvil-pr

是只读的，仅发布审查评论，而本预设会实际修改代码：它会提前在PR上宣告自身启动，以

commit_mode=per_fix

运行审查循环，在指定轮次及自适应延续过程中，将修复提交应用到本地分支，推送结果以更新PR，然后原地编辑启动评论，替换为合成报告（或失败摘要）——PR时间线中仅一条评论，两种状态。

Generated Language

生成语言规范

Apply the ASD-STE100-inspired language contract to this preset. Use direct imperatives for internal steps. Use short active declarative sentences in PR comments. Use

**What to change**

only for multiple actions the author must perform; keep no-change constraints in prose. Retain suggestion grammar for low/nit guidance.

The skill orchestrates six steps:

```
scripts/pr-helper.sh verify-checkout [<locator>]
```
— locator parsing or auto-detect, then verify the local checkout matches the PR's head branch and is in a clean state. Captures the PR's base branch, author, marker UUID, and report path.
```
scripts/pr-helper.sh post-start
```
— post a "starting" top-level PR comment cc'ing the original author, explaining what's about to happen and that the comment will be edited with the final summary. Captures the comment's ID (for the later edit) and start timestamp. The author gets a GitHub notification.
The
```
review-anvil
```
engine in
```
commit_mode=per_fix
```
on a branch-vs-base diff (NOT a PR-locator target — the engine's "PR-target / per_fix incompatibility" rule forbids that combination; this preset deliberately routes around it by targeting the local branch directly). The engine writes the final synthesized report to
```
report_path
```
— on failure paths too.
```
git push
```
— once, after requested rounds plus any adaptive continuation complete (or converge early) and only if the engine reported no failures and the build/test gate ended green, to publish the fix commits to the PR.
```
scripts/pr-helper.sh post-update
```
— PATCH-edit the starting comment to replace its body with the full final report (outcome=success) or a failure summary (outcome=failure). GitHub does NOT notify on edits, so the author isn't pinged again — the original
```
cc @author
```
notification at step 2 is the only ping.
Surface the final report inline + the comment URL to the user.

为该预设应用受ASD-STE100启发的语言协议。内部步骤使用直接祈使句。PR评论中使用简短的主动式陈述句。仅当作者需执行多项操作时使用

**What to change**

；无修改约束的内容以散文形式呈现。低优先级/细枝末节的指导保留建议性语法。

该技能编排六个步骤：

```
scripts/pr-helper.sh verify-checkout [<locator>]
```
— 解析定位符或自动检测，然后验证本地检出分支与PR的头部分支匹配且处于干净状态。捕获PR的基准分支、作者、标记UUID和报告路径。
```
scripts/pr-helper.sh post-start
```
— 发布一条提及原作者的顶级「启动中」PR评论，说明即将执行的操作以及该评论将被编辑为最终摘要。捕获评论ID（用于后续编辑）和启动时间戳。作者会收到GitHub通知。
以
```
commit_mode=per_fix
```
模式运行
```
review-anvil
```
引擎，针对分支与基准的差异（而非PR定位符目标——引擎的「PR目标 / per_fix不兼容」规则禁止该组合；本预设通过直接定位本地分支特意规避此限制）。引擎将最终合成报告写入
```
report_path
```
——失败路径下也会执行此操作。
```
git push
```
— 仅在指定轮次及所有自适应延续完成（或提前收敛），且引擎报告无失败、构建/测试网关最终为绿色时执行一次，将修复提交发布到PR。
```
scripts/pr-helper.sh post-update
```
— 通过PATCH编辑启动评论，将其内容替换为完整的最终报告（结果=成功）或失败摘要（结果=失败）。GitHub不会对编辑操作发送通知，因此作者不会再次被提及——步骤2中最初的
```
cc @author
```
通知是唯一的提醒。
向用户内联展示最终报告及评论URL。

Inputs

输入参数

Same locator forms as

review-anvil-pr

— but you must already be on the PR's branch:

Omitted — auto-detect via
```
gh pr view
```
; works when you're checked out on a PR branch.
Full GitHub URL —
```
https://<host>/<owner>/<repo>/pull/<N>
```
for github.com or GitHub Enterprise.
Slug —
```
<owner>/<repo>#<N>
```
(host defaults to github.com).

The helper script aborts cleanly if the current checkout doesn't match the named PR (wrong branch, dirty worktree, detached HEAD, divergent SHA). This is the safety net for "I'm on PR #42's branch, run improve" — without it, the engine could commit fixes to an unrelated local branch.

与

review-anvil-pr

支持相同的定位符格式——但你必须已处于PR的分支上：

省略 — 通过
```
gh pr view
```
自动检测；当你已检出PR分支时生效。
完整GitHub URL — 适用于github.com或GitHub Enterprise的
```
https://<host>/<owner>/<repo>/pull/<N>
```
。
缩写格式 —
```
<owner>/<repo>#<N>
```
（主机默认值为github.com）。

若当前检出内容与指定PR不匹配（分支错误、工作区脏、分离HEAD、SHA分歧），辅助脚本会干净地终止。这是「我在PR #42的分支上，执行改进操作」场景的安全保障——若无此机制，引擎可能会将修复提交到无关的本地分支。

How to invoke

调用方式

0. Reject overrides of pinned params

0. 拒绝覆盖固定参数

Pins for this preset:

commit_mode

target

report_path

run_ordinal

. Enforce mechanically — after resolving the helper (step 1), run:

bash

bash <helper-path> check-pins review-anvil-improve-pr "commit_mode,target,report_path,run_ordinal" "$ARGUMENTS"

Non-zero exit means a pinned param was overridden: surface the error verbatim and stop.

The pins are non-overridable for safety:

commit_mode=per_fix

is the whole point of this preset (read-only is what

review-anvil-pr

is for),

target=<base>...HEAD

is mechanically tied to the verified PR,

report_path

is the file the post-summary step needs to read after the engine finishes, and

run_ordinal

carries the helper's observed PR history into identifier generation.

本预设的固定参数：

commit_mode

、

target

、

report_path

、

run_ordinal

。需机械性强制执行——解析辅助脚本后（步骤1），运行：

bash

bash <helper-path> check-pins review-anvil-improve-pr "commit_mode,target,report_path,run_ordinal" "$ARGUMENTS"

非零退出码表示固定参数被覆盖：直接显示错误信息并终止。

这些参数不可覆盖是出于安全考虑：

commit_mode=per_fix

是本预设的核心价值（只读功能由

review-anvil-pr

实现），

target=<base>...HEAD

与已验证的PR机械绑定，

report_path

是提交摘要步骤在引擎完成后需要读取的文件，

run_ordinal

将辅助脚本观察到的PR历史带入标识符生成过程。

1. Resolve the helper script

1. 解析辅助脚本

The helper lives at

../review-anvil-pr/scripts/pr-helper.sh

relative to this SKILL.md — this preset reuses the script from

review-anvil-pr

rather than duplicating it. Resolve it exactly per

review-anvil-pr

SKILL.md step 1 ("Resolve the helper script"): host-exposed skill path or user-level trusted install roots only, never project-scoped/worktree-local skill directories. If no trusted copy resolves, abort with

error: review-anvil-pr/scripts/pr-helper.sh not found in any trusted skill root; install via 'npx skills add mrshu/agent-skills --skill review-anvil-pr'

(yes, the dependency is on

review-anvil-pr

, not on

review-anvil-improve-pr

itself).

辅助脚本位于本SKILL.md的相对路径

../review-anvil-pr/scripts/pr-helper.sh

——本预设复用

review-anvil-pr

的脚本而非重复编写。需完全按照

review-anvil-pr

SKILL.md的步骤1（「解析辅助脚本」）进行解析：仅使用主机暴露的技能路径或用户级可信安装根目录，绝不能使用项目范围/工作树本地的技能目录。若无法解析到可信副本，终止并提示

error: review-anvil-pr/scripts/pr-helper.sh not found in any trusted skill root; install via 'npx skills add mrshu/agent-skills --skill review-anvil-pr'

（是的，依赖项是

review-anvil-pr

，而非

review-anvil-improve-pr

本身）。

2. Verify checkout

2. 验证检出状态

bash

bash <helper-path> verify-checkout "<locator>"   # explicit form
bash <helper-path> verify-checkout               # auto-detect from current branch

The script runs

gh

preflight (auth + PR reachability), then verifies the local checkout: current branch matches the PR's head branch, HEAD is at-or-descended-from the PR's head SHA (descendants OK — unpushed local commits will be pushed at the end), and the worktree+index are clean. It also fetches the PR's base branch locally so the engine's diff target works.

On success, the script prints these KEY=VALUE lines on stdout:

HOST=github.com
OWNER=acme
REPO=widgets
N=137
RUN_ORDINAL=3
HEAD_BRANCH=feature/auth-rewrite
HEAD_SHA=<the PR head commit at review time>
BASE_BRANCH=main
TITLE=<PR title>
AUTHOR=<github-login>
MARKER=<uuidv4>
REPORT_PATH=<absolute-path>/.review-anvil/final-report-<uuidv4>.md

If the locator was auto-detected, the script also prints

auto-detected PR: <url>

to stderr before the KEY=VALUE block. If HEAD is ahead of the PR's published head (unpushed local commits), the script prints a

note:

to stderr — surface that to the user so they know what will get pushed.

Capture all values, including

RUN_ORDINAL

. Echo to the user:

improving PR: $HOST/$OWNER/$REPO#$N — $TITLE ($HEAD_BRANCH → $BASE_BRANCH), author: @$AUTHOR

On non-zero exit, surface the script's stderr verbatim and stop. Do not dispatch reviewers.

Then fetch the PR's complete status-aware review history for the reviewer prompts:

bash

bash <helper-path> history "$HOST" "$OWNER" "$REPO" "$N"

Capture the output — an itemized open/resolved/outdated/reported/suppressed ledger, or

None.

— for step 4. On non-zero exit, abort: every PR run must account for feedback already shown to the author.

The helper resolves

RUN_ORDINAL

during this preflight, before step 3 posts the starting comment. The unfinished current starting comment therefore cannot count itself as a finalized review run.

bash

bash <helper-path> verify-checkout "<locator>"   # 显式形式
bash <helper-path> verify-checkout               # 从当前分支自动检测

脚本运行

gh

预检查（授权 + PR可达性），然后验证本地检出状态：当前分支与PR的头部分支匹配，HEAD位于PR头部SHA或其后代（后代状态允许——未推送的本地提交将在最后被推送），工作区+索引处于干净状态。它还会在本地拉取PR的基准分支，以便引擎的差异目标生效。

成功时，脚本在标准输出打印以下KEY=VALUE行：

HOST=github.com
OWNER=acme
REPO=widgets
N=137
RUN_ORDINAL=3
HEAD_BRANCH=feature/auth-rewrite
HEAD_SHA=<审查时的PR头部提交>
BASE_BRANCH=main
TITLE=<PR标题>
AUTHOR=<github-login>
MARKER=<uuidv4>
REPORT_PATH=<绝对路径>/.review-anvil/final-report-<uuidv4>.md

若定位符是自动检测的，脚本还会在打印KEY=VALUE块前向标准错误输出

auto-detected PR: <url>

。若HEAD领先于PR已发布的头部（存在未推送的本地提交），脚本会向标准错误输出一条

note:

——需向用户展示此信息，使其了解将被推送的内容。

捕获所有值，包括

RUN_ORDINAL

。向用户回显：

improving PR: $HOST/$OWNER/$REPO#$N — $TITLE ($HEAD_BRANCH → $BASE_BRANCH), author: @$AUTHOR

。

非零退出码时，直接显示脚本的标准错误输出并终止，不调度审查器。

然后为审查器提示获取PR的完整状态感知审查历史：

bash

bash <helper-path> history "$HOST" "$OWNER" "$REPO" "$N"

捕获输出——一个分项列出的开放/已解决/已过时/已报告/已抑制的记录，或

None.

——用于步骤4。非零退出码时终止：每次PR运行都必须考虑已向作者展示的反馈。

辅助脚本在预检查期间（步骤3发布启动评论之前）解析

RUN_ORDINAL

。因此，未完成的当前启动评论不会被算作已完成的审查运行。

3. Post the "starting" comment

3. 发布「启动中」评论

Before any review work begins:

bash

bash <helper-path> post-start "$HOST" "$OWNER" "$REPO" "$N" "$MARKER" "$AUTHOR"

The script creates a top-level PR comment that:

Embeds the marker UUID (for later lookup if needed).

Begins

review-anvil-improve-pr started on this PR. cc @<author>.

Explains what's about to happen and that the comment will be edited with the final result.
Includes a
```
Started: <ISO-8601 UTC>
```
timestamp.

Then it looks up the comment by marker (with one retry for read-after-write lag), captures the comment ID + URL, and prints these KEY=VALUE lines:

COMMENT_ID=12345678
COMMENT_URL=https://github.com/acme/widgets/pull/137#issuecomment-12345678
STARTED_AT=2026-06-07T10:00:00Z

Capture all three. Echo to the user:

starting comment posted: $COMMENT_URL

. The PR author receives a GitHub notification from the

@-mention

post-start

fails before posting (network blip, gh auth issue), abort — nothing to clean up. One failure mode is different: the script can die after posting, when the marker lookup can't recover the comment ID ("posted starting comment but could not recover its ID"). In that case a starting comment does exist on the PR — abort the run and apply the Recovery procedure below to edit it manually.

在开始任何审查工作前：

bash

bash <helper-path> post-start "$HOST" "$OWNER" "$REPO" "$N" "$MARKER" "$AUTHOR"

脚本创建一条顶级PR评论，内容包括：

嵌入标记UUID（如需后续查找）。

开头为

review-anvil-improve-pr started on this PR. cc @<author>.

。

说明即将执行的操作以及该评论将被编辑为最终结果。
包含
```
Started: <ISO-8601 UTC>
```
时间戳。

然后它通过标记查找评论（为解决写入后读取延迟问题进行一次重试），捕获评论ID + URL，并打印以下KEY=VALUE行：

COMMENT_ID=12345678
COMMENT_URL=https://github.com/acme/widgets/pull/137#issuecomment-12345678
STARTED_AT=2026-06-07T10:00:00Z

捕获这三个值。向用户回显：

starting comment posted: $COMMENT_URL

。PR作者会收到来自

@-mention

的GitHub通知。

若

post-start

在发布前失败（网络中断、gh授权问题），终止——无需清理。有一种不同的失败模式：脚本可能在发布后终止，此时标记查找无法恢复评论ID（"已发布启动评论但无法恢复其ID"）。这种情况下PR上确实存在一条启动评论——终止运行并按照下面的恢复流程手动编辑它。

4. Activate the engine

4. 激活引擎

Activate the

review-anvil

skill with this argument string (extra user args go after the pinned params; the engine's own

rounds: 3

default and its diff-size-scaled

max_rounds

cap apply when the user doesn't pass them):

commit_mode: per_fix, target: <BASE_BRANCH>...HEAD, report_path: <REPORT_PATH>, run_ordinal: <RUN_ORDINAL>, <extra-user-args>

<BASE_BRANCH>

<REPORT_PATH>

, and

<RUN_ORDINAL>

come from step 2. Using

<BASE_BRANCH>...HEAD

(three-dot diff) targets exactly the commits that distinguish this PR from its base. Pinning

report_path

makes the engine write the final synthesized report to a file that step 6 (

post-update

) can read.

The user cannot override the observed value of

run_ordinal

. When

RUN_ORDINAL

is a positive integer, the engine includes the corresponding

RUN

segment in new provenance IDs. The value

unavailable

makes the engine emit IDs without the

RUN

segment; degraded history must not invent a run number.

Supply the ledger captured in step 2 as the engine's

PR REVIEW HISTORY

reviewer-prompt block — the branch target means the engine won't fetch it itself. Reviewers must revalidate open, resolved, and summary-only reported items against the current head; resolved is conversation state, not proof of a fix.

Note: do not pin a PR locator as

target

— the engine's "PR-target / per_fix incompatibility" rule would force

commit_mode=none

and defeat the point of this preset. Targeting the branch directly is the intended escape hatch.

The user may override

rounds:

max_rounds:

(defaults are the engine's

rounds: 3

and its diff-size-scaled

max_rounds

cap —

rounds

plus 1–3 adaptive rounds, never above the legacy

max(6, rounds)

). They cannot override

run_ordinal

commit_mode

target

, or

report_path

; these are pinned for safety, and the step-0 segment-rejection above blocks override attempts.

The engine runs the multi-round loop, committing fix-groups along the way and writing the final synthesized report to

<REPORT_PATH>

when it's done. The engine's default reproduction pass confirms uncertain material findings before they can become fix commits, and the build/test gate (

verify_cmd

, auto-detected unless the user passes one) runs after each round's fixes. Together, the report's Reproduction and Verification lines are the evidence the PR author needs to trust the pushed commits — if the engine recorded

Verification: none detected

, that caveat travels to the PR in the posted report. If reproduction fails for required candidates, those candidates are Deferred and the loop may still finish with other verified fixes. If any round fails (reviewer-all-fail, git-commit error, build/test gate newly red after the revert path), the engine stops the loop and surfaces the failure — skip the push (step 5) and call
post-update
with
outcome=failure
(step 6) so the starting comment gets replaced with a failure summary rather than dangling.

使用以下参数字符串激活

review-anvil

技能（额外用户参数放在固定参数之后；当用户未传递时，引擎默认的

rounds: 3

及其基于差异大小缩放的

max_rounds

上限生效）：

commit_mode: per_fix, target: <BASE_BRANCH>...HEAD, report_path: <REPORT_PATH>, run_ordinal: <RUN_ORDINAL>, <extra-user-args>

<BASE_BRANCH>

、

<REPORT_PATH>

和

<RUN_ORDINAL>

来自步骤2。使用

<BASE_BRANCH>...HEAD

（三点差异）精确针对PR与其基准分支的差异提交。固定

report_path

可使引擎将最终合成报告写入步骤6（

post-update

）可读取的文件。

用户无法覆盖

run_ordinal

的观测值。当

RUN_ORDINAL

为正整数时，引擎会在新的来源ID中包含相应的

RUN

段。值为

unavailable

时，引擎会生成不带

RUN

段的ID；历史记录不完整时不得生成运行编号。

将步骤2中捕获的记录作为引擎的

PR REVIEW HISTORY

审查器提示块提供——分支目标意味着引擎不会自行获取它。审查器必须针对当前头部重新验证开放、已解决和仅摘要的已报告项；已解决是对话状态，而非修复的证明。

注意：不要将PR定位符固定为

target

——引擎的「PR目标 / per_fix不兼容」规则会强制

commit_mode=none

，从而违背本预设的初衷。直接定位分支是预期的规避方式。

用户可以覆盖

rounds:

或

max_rounds:

（默认值为引擎的

rounds: 3

及其基于差异大小缩放的

max_rounds

上限——

rounds

加1–3轮自适应轮次，绝不超过旧版的

max(6, rounds)

）。他们无法覆盖

run_ordinal

、

commit_mode

、

target

或

report_path

；这些参数出于安全考虑被固定，且步骤0的段拒绝逻辑会阻止覆盖尝试。

引擎运行多轮循环，沿途提交修复组，并在完成时将最终合成报告写入

<REPORT_PATH>

。引擎的默认复现步骤会在不确定的重要发现成为修复提交前进行确认，构建/测试网关（

verify_cmd

，除非用户传递否则自动检测）会在每轮修复后运行。报告中的复现和验证行是PR作者信任推送提交所需的证据——若引擎记录

Verification: none detected

，该说明会随报告发布到PR。若所需候选项的复现失败，这些候选项会被推迟，循环仍可能完成其他已验证的修复。若任何一轮失败（所有审查器失败、git提交错误、回滚路径后构建/测试网关变为红色），引擎会停止循环并显示失败信息——跳过推送（步骤5），调用
post-update
并传入
outcome=failure
（步骤6），使启动评论被替换为失败摘要而非处于悬停状态。

5. Push

5. 推送

Only after the engine reports a successful run: all requested rounds and any adaptive continuation completed (or the loop converged early — that counts as success), no

git commit failed

all reviewers failed

errors in the round summaries, and every round's Verification state is one of

passed

failed → round reverted

pre-existing failures (no new)

none detected

, or

skipped

— i.e. never newly red (these are exactly the engine's round-summary states). Deferred reproduction candidates do not block the push by themselves; they also must not produce fix commits or actionable PR comments.

bash

git push origin "$HEAD_BRANCH"

If the engine's run was partial or failed, do not push. Go straight to step 6 with

outcome=failure

. The report file at

<REPORT_PATH>

contains the engine's final state including failure details;

post-update

will use it to populate the comment.

If the engine succeeded but

git push

fails (permission denied, conflict, etc.), the fix commits exist locally but didn't reach the PR. Still call step 6 with

outcome=failure

so the comment reflects the actual state. Tell the user the local commits remain in

<HEAD_BRANCH>

for them to investigate.

仅当引擎报告运行成功时执行：所有指定轮次及自适应延续已完成（或循环提前收敛——这也算成功），轮次摘要中无

git commit failed

或

all reviewers failed

错误，且每轮的验证状态为以下之一：

passed

、

failed → round reverted

、

pre-existing failures (no new)

、

none detected

或

skipped

——即绝不能是新出现的红色状态（这些正是引擎的轮次摘要状态）。推迟的复现候选项本身不会阻止推送；它们也不得生成修复提交或可执行的PR评论。

bash

git push origin "$HEAD_BRANCH"

若引擎运行部分完成或失败，不要推送。直接进入步骤6并传入

outcome=failure

。

<REPORT_PATH>

处的报告文件包含引擎的最终状态，包括失败详情；

post-update

会使用它填充评论内容。

若引擎成功但

git push

失败（权限被拒绝、冲突等），修复提交存在于本地但未推送到PR。仍需调用步骤6并传入

outcome=failure

，使评论反映实际状态。告知用户本地提交仍保留在

<HEAD_BRANCH>

中，供他们排查。

6. Update the comment with the final summary

6. 更新评论为最终摘要

Always run this step, regardless of step 4/5 outcome. Pass

outcome=success

only if both the engine and the push completed cleanly:

bash

bash <helper-path> post-update "$HOST" "$OWNER" "$REPO" "$N" "$COMMENT_ID" "$MARKER" "$REPORT_PATH" "$AUTHOR" "$OUTCOME" "$STARTED_AT"

On a

success

outcome the helper refreshes the full prior-feedback ledger and re-applies duplicate-thread suppression before editing the comment. If that lookup fails, it changes the update to

outcome=failure

and explains why in the comment; it never posts an unfiltered success report, and it still avoids leaving a dangling "starting" comment.

The helper posts the report body as written instead of compacting or shortening it. If GitHub rejects an unusually large payload, the update fails loudly and leaves the report artifact in place; the running agent should rewrite the report with the same findings, rationale, and actionable detail in a better organized form, then retry the update.

$OUTCOME

success

failure

. The script PATCH-edits the starting comment (identified by

$COMMENT_ID

), replacing its body entirely with:

A header line:

review-anvil-improve-pr completed on this PR. cc @<author>.

(success) OR

review-anvil-improve-pr **failed** on this PR. cc @<author>.

(failure).

A horizontal rule + the full report from
```
<REPORT_PATH>
```
.

A footer:

Started: $STARTED_AT; Completed: <ISO-8601 UTC> (outcome: <outcome>)

GitHub does not notify on comment edits, so the author isn't pinged again — the original

cc @author

notification from step 3 is the only ping.

Before calling

post-update

on a success outcome, read

<REPORT_PATH>.followups.json

(if present) and surface its entries to the user — the script deletes it afterwards. The script cleans up all four artifacts (

<REPORT_PATH>

.inline.json

.approval.json

.followups.json

) and removes the

.review-anvil/

directory when no other run's artifacts remain.

post-update

itself fails (rare: transient

gh

issue, comment was deleted by hand mid-run), surface the error but do not undo the push — the fix commits are already on the PR and a missing comment edit is recoverable. The user can manually edit the starting comment using the comment ID. The report file remains on disk for that purpose (cleanup is skipped on

post-update

failure).

无论步骤4/5的结果如何，都必须运行此步骤。仅当引擎和推送均顺利完成时，传递

outcome=success

：

bash

bash <helper-path> post-update "$HOST" "$OWNER" "$REPO" "$N" "$COMMENT_ID" "$MARKER" "$REPORT_PATH" "$AUTHOR" "$OUTCOME" "$STARTED_AT"

在

success

结果下，辅助脚本会刷新完整的先前反馈记录并在编辑评论前重新应用重复线程抑制。若查找失败，它会将更新改为

outcome=failure

并在评论中解释原因；它绝不会发布未过滤的成功报告，且仍会避免留下悬停的「启动中」评论。

辅助脚本按原样发布报告内容，不进行压缩或缩短。若GitHub拒绝异常大的负载，更新会失败并保留报告工件；运行中的代理应重新组织报告内容，保留相同的发现、理由和可执行细节，然后重试更新。

$OUTCOME

为

success

或

failure

。脚本通过PATCH编辑启动评论（由

$COMMENT_ID

标识），将其内容完全替换为：

标题行：

review-anvil-improve-pr completed on this PR. cc @<author>.

（成功）或

review-anvil-improve-pr **failed** on this PR. cc @<author>.

（失败）。

一条水平线 +
```
<REPORT_PATH>
```
中的完整报告。

页脚：

Started: $STARTED_AT; Completed: <ISO-8601 UTC> (outcome: <outcome>)

。

GitHub不会对评论编辑发送通知，因此作者不会再次被提及——步骤3中最初的

cc @author

通知是唯一的提醒。

在成功结果下调用

post-update

前，读取

<REPORT_PATH>.followups.json

（若存在）并向用户展示其条目——脚本随后会删除它。当没有其他运行的工件剩余时，脚本会清理所有四个工件（

<REPORT_PATH>

、

.inline.json

、

.approval.json

、

.followups.json

）并删除

.review-anvil/

目录。

若

post-update

本身失败（罕见：临时

gh

问题、运行中评论被手动删除），显示错误信息但不要撤销推送——修复提交已在PR上，缺失的评论编辑可恢复。用户可以使用评论ID手动编辑启动评论。报告文件会保留在磁盘上用于此目的（

post-update

失败时会跳过清理）。

7. Report back

7. 反馈结果

Surface the engine's final report inline. Echo a two-line summary:

pushed N commits to $HOST/$OWNER/$REPO#$N ($HEAD_BRANCH)

with

from the pushed fix commits or the final report's

Changes made / Things to try

list. If step 5 was skipped (failure path), say

did not push (engine/run failure)

instead.

comment $COMMENT_URL updated with outcome=$OUTCOME

(or

comment update failed: ...

if step 6 errored).

向用户内联展示引擎的最终报告。回显两行摘要：

pushed N commits to $HOST/$OWNER/$REPO#$N ($HEAD_BRANCH)

，其中

来自推送的修复提交或最终报告的

Changes made / Things to try

列表。若跳过步骤5（失败路径），则改为显示

did not push (engine/run failure)

。

comment $COMMENT_URL updated with outcome=$OUTCOME

（若步骤6出错，则显示

comment update failed: ...

）。

Examples

示例

"Improve the PR I'm on." — user is checked out on a PR branch; agent invokes
```
verify-checkout
```
with no locator; helper auto-detects.
"Run 5 rounds on acme/widgets#137." — user passes the slug and asks for more rounds; engine default is overridden via the trailing
```
rounds: 5
```
arg.
"Review and improve this PR with focus on production safety." — user asks for a non-default focus; flows through as
```
focus: production blast-radius
```
(or similar) to the engine.

"改进我当前所在的PR。" — 用户已检出PR分支；代理调用无定位符的
```
verify-checkout
```
；辅助脚本自动检测。
"对acme/widgets#137运行5轮。" — 用户传递缩写格式并要求更多轮次；通过末尾的
```
rounds: 5
```
参数覆盖引擎默认值。
"审查并改进此PR，重点关注生产环境安全性。" — 用户要求非默认的审查重点；会以
```
focus: production blast-radius
```
（或类似形式）传递给引擎。

Constraints

约束条件

Requires
```
gh
```
,
```
uuidgen
```
,
```
jq
```
(a real binary — gh's
```
--jq
```
is built-in gojq and doesn't count), plus
```
uv
```
(preferred; falls back to
```
python3
```
) for PR-feedback history handling.
```
verify-checkout
```
preflights all of these so a missing dependency fails before the expensive review. The helper honors the same environment switches as
```
review-anvil-pr
```
(
```
REVIEW_ANVIL_NO_APPROVE
```
, legacy-named
```
REVIEW_ANVIL_SKIP_DISMISSED
```
,
```
REVIEW_ANVIL_DISMISSALS
```
).
Mutates the local working tree and pushes to the PR. Use
```
review-anvil-pr
```
(read-only + comment) when you only want feedback without applying fixes.
The user must already be on the PR's branch with a clean worktree. The verify-checkout step enforces this and gives clear recovery instructions on failure (e.g.
```
gh pr checkout <N>
```
).
The PR must be one you have push access to.
```
git push
```
will fail with a normal git error if not — the script doesn't pre-check push permissions.
Supports github.com and GitHub Enterprise — same handling as
```
review-anvil-pr
```
.

要求PATH中存在
```
gh
```
、
```
uuidgen
```
、
```
jq
```
（真实二进制文件——gh的
```
--jq
```
是内置的gojq，不算在内），以及
```
uv
```
（首选； fallback到
```
python3
```
）用于PR反馈历史处理。
```
verify-checkout
```
会预检查所有这些依赖项，因此缺失依赖会在昂贵的审查前失败。辅助脚本遵循与
```
review-anvil-pr
```
相同的环境开关（
```
REVIEW_ANVIL_NO_APPROVE
```
、旧命名的
```
REVIEW_ANVIL_SKIP_DISMISSED
```
、
```
REVIEW_ANVIL_DISMISSALS
```
）。
会修改本地工作树并推送到PR。若仅需反馈而不应用修复，请使用
```
review-anvil-pr
```
（只读 + 评论）。
用户必须已处于PR分支且工作区干净。verify-checkout步骤会强制执行此要求，并在失败时给出明确的恢复说明（例如
```
gh pr checkout <N>
```
）。
你必须拥有PR的推送权限。若无权限，
```
git push
```
会抛出常规git错误——脚本不会预先检查推送权限。
支持github.com和GitHub Enterprise——处理方式与
```
review-anvil-pr
```
相同。

Recovery: dangling "starting" comment

恢复：悬停的「启动中」评论

The two-step

post-start

post-update

flow has one failure mode the previous one-shot didn't: if the orchestrator crashes (or the agent host loses context, or the user interrupts) between step 3 and step 6, the PR is left with a "starting" comment that promises an edit-that-never-comes. The fix commits may or may not have been pushed depending on where the crash happened.

This is rare but recoverable. If you find a dangling starting comment:

Find the comment URL on the PR. The body starts with
```

```
and
```
review-anvil-improve-pr started on this PR.
```
The numeric comment ID is at the end of the URL (
```
...#issuecomment-<ID>
```
).

Edit the comment manually with

gh api

bash

gh api repos/<owner>/<repo>/issues/comments/<COMMENT_ID> -X PATCH \
  -F body="review-anvil-improve-pr failed: orchestrator did not complete. No reliable summary available."

Or use the GitHub web UI's "Edit" menu on the comment.

If the orchestrator is still alive and the engine completed but step 6 was somehow skipped, the report is still on disk at the path printed by step 4 — you can paste it into the edit body verbatim.

If the engine never ran (crash between steps 3 and 4), nothing was pushed; just edit the comment to a "did not complete" note as above.

两步式的

post-start

post-update

流程存在一种之前单次流程没有的失败模式：若编排器崩溃（或代理主机丢失上下文，或用户中断）在步骤3和步骤6之间，PR会留下一条「启动中」评论，承诺的编辑从未兑现。根据崩溃发生的位置，修复提交可能已被推送或未被推送。

这种情况罕见但可恢复。若发现悬停的启动评论：

在PR上找到评论URL。内容以

<!-- review-anvil-marker: <UUID> -->

和

review-anvil-improve-pr started on this PR.

开头。数字评论ID位于URL末尾（

...#issuecomment-<ID>

）。

使用

gh api

手动编辑评论：

bash

gh api repos/<owner>/<repo>/issues/comments/<COMMENT_ID> -X PATCH \
  -F body="review-anvil-improve-pr failed: orchestrator did not complete. No reliable summary available."

或使用GitHub网页UI上的「编辑」菜单。

若编排器仍在运行且引擎已完成但步骤6被跳过，报告仍在步骤4打印的路径下——你可以将其原样粘贴到编辑内容中。

若引擎从未运行（步骤3和4之间崩溃），则未推送任何内容；只需将评论编辑为「未完成」说明即可。

Pairing

依赖关系

Depends on the

review-anvil

engine AND the

review-anvil-pr

preset (whose

scripts/pr-helper.sh

this skill reuses). All three ship in the same plugin and should be installed together (

npx skills add mrshu/agent-skills --skill review-anvil --skill review-anvil-pr --skill review-anvil-improve-pr

, or just

--all

依赖

review-anvil

引擎和

review-anvil-pr

预设（本技能复用其

scripts/pr-helper.sh

脚本）。三者在同一插件中发布，应一起安装（

npx skills add mrshu/agent-skills --skill review-anvil --skill review-anvil-pr --skill review-anvil-improve-pr

，或直接使用

--all

）。