pr-improver

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

PR Improver

PR 改进工具

Improve the current branch by running

/code-improver:improve

— a dynamic workflow that loops a PR reviewer and a fixer subagent over the branch's changes until a review reports zero critical/major findings. The loop, its ledger, and its guards live in the workflow; this skill derives the scope from the branch diff and relays the outcome.

通过运行

/code-improver:improve

来改进当前分支——这是一个动态工作流，会让PR审查器和修复子Agent循环处理分支变更，直到审查报告显示无严重/主要问题为止。循环逻辑、记录台账和防护机制都内置在工作流中；本skill会从分支差异中推导审查范围，并传达处理结果。

Starting the loop

启动循环

The user provided:

$ARGUMENTS

(if empty, take base branch and preferences from the conversation).

用户提供的参数：

$ARGUMENTS

（若为空，则从对话中获取基准分支和偏好设置）。

1. Resolve the branch and its change surface

1. 解析分支及其变更范围

Repo root:
```
git rev-parse --show-toplevel
```
. Fail loudly outside a repository.
Base: the argument if given, else the repository's default branch (
```
git symbolic-ref refs/remotes/origin/HEAD
```
→ its short name, falling back to
```
main
```
). Refuse to run when the current branch IS the base — there is no diff to improve.
Changed files:
```
git diff --name-only <base>...HEAD
```
. If empty, say so and stop.
Scope: the changed files' directories, widened — per-file globs are too tight (PR fixes legitimately add tests next to changed code). Map each changed file to its repo-relative directory glob
```
<dir>/**
```
(
```
**
```
at the repo root only if files at the root changed), then deduplicate and drop globs covered by another.

仓库根目录：
```
git rev-parse --show-toplevel
```
。若不在仓库内则直接报错终止。
基准分支：若用户提供了参数则使用该参数，否则使用仓库的默认分支（通过
```
git symbolic-ref refs/remotes/origin/HEAD
```
获取其短名称，若失败则回退为
```
main
```
）。若当前分支即为基准分支则拒绝运行——此时没有可改进的差异内容。
变更文件：
```
git diff --name-only <base>...HEAD
```
。若结果为空则告知用户并终止。
审查范围：变更文件对应的目录，适当扩大范围——按文件匹配的通配符过于严格（PR修复通常会在变更代码旁添加测试用例）。将每个变更文件映射为仓库相对路径的目录通配符
```
<dir>/**
```
（仅当根目录下的文件变更时，根目录才使用
```
**
```
），然后去重并移除被其他通配符覆盖的项。

2. Resolve the loop script

2. 解析循环脚本

The loop is the dynamic workflow

workflows/improve.js

in this plugin. Launch it by path:

scriptPath

takes a resolved absolute path, and the Workflow tool's

name

resolves built-in and project workflows, so a marketplace-installed one may not answer to

code-improver:improve

. Try in order, first hit wins — the home directories come before

so an installed copy beats a checkout of this marketplace:

Bash: ls -d -- "${CLAUDE_PLUGIN_ROOT}/workflows/improve.js"

Bash: ls -d -- "${CODEX_PLUGIN_ROOT}/workflows/improve.js"

(if that variable is set instead)

Bash: find ~/.claude ~/.codex . -maxdepth 7 -path '*/code-improver/workflows/improve.js' -print -quit 2>/dev/null

Use the path exactly as printed. Its plugin directory — the path with

/workflows/improve.js

removed — is

pluginRoot

. If all three come back empty, try

{name: "code-improver:improve"}

once; if that is unavailable too, stop and say the loop could not be located. Do not assemble a path by hand and do not improvise the loop.

循环逻辑是本插件中的动态工作流

workflows/improve.js

。通过路径启动：

scriptPath

需传入解析后的绝对路径，而Workflow工具的

name

参数可解析内置和项目工作流，因此市场安装的工作流可能无法通过

code-improver:improve

直接调用。按以下顺序尝试，找到第一个可用路径即可——主目录优先于

，因此安装版会优先于本地克隆的市场版本：

Bash: ls -d -- "${CLAUDE_PLUGIN_ROOT}/workflows/improve.js"

Bash: ls -d -- "${CODEX_PLUGIN_ROOT}/workflows/improve.js"

（若该变量已设置）

Bash: find ~/.claude ~/.codex . -maxdepth 7 -path '*/code-improver/workflows/improve.js' -print -quit 2>/dev/null

完全使用打印出的路径。移除

/workflows/improve.js

后的路径即为

pluginRoot

。若以上三种方式均返回空，则尝试使用

{name: "code-improver:improve"}

；若仍不可用，则终止并告知用户无法找到循环脚本。请勿手动拼接路径或自行编写循环逻辑。

3. Invoke the workflow

3. 调用工作流

Run it with the Workflow tool,

{scriptPath: "<the path from step 2>", args: {...}}

json

{
  "target": "<repo root>",
  "reviewer": {
    "kind": "skill",
    "name": "pr-review-toolkit:review-pr",
    "notes": "Review the working tree's changes against <base> as a pull request: correctness, tests, error handling, and the review dimensions the skill prescribes."
  },
  "scope": ["<derived-dir-glob>/**"],
  "pluginRoot": "<the plugin directory from step 2>",
  "maxRounds": 5
}

```
reviewer
```
— the default above requires the
```
pr-review-toolkit
```
plugin. When the user names a different PR reviewer (skill or agent), use it, with kind set accordingly.
```
maxRounds
```
only if the user asked for a different cap.
```
pluginRoot
```
lets the run find its metrics collector; omit the key only if step 2 fell through to the workflow name — the workflow then searches for itself.
```
finalize
```
defaults are right for PRs: no version bump unless the branch sits inside a plugin, narration strip and docs pass on.
```
decision
```
only on continuation (below).

The loop's baseline snapshot is the tree at loop start — its scope guard protects the branch's uncommitted work; the PR's own commits are what the reviewer reviews.

The workflow runs in the background and needs no babysitting: it reviews, fixes, re-reviews, checks scope after every fix round, and can only complete on a clean review. It never commits; all changes stay in the working tree.

If the Workflow tool is unavailable or denied, stop and say so. Do not improvise the loop inline with direct edits — the ledger, scope guard, and escalation guarantees live in the workflow, and an inline imitation has none of them.

If the result is
halted: "reviewer-unavailable"
, relay it and stop. The reviewer is not installed in this session; tell the user which plugin provides it (the default needs

pr-review-toolkit

) and re-run after installing. Do not review the branch yourself.

Do not end your turn while the loop is running. The Workflow tool returns a task id immediately; the result comes later. In an interactive session the completion notification re-invokes you — wait for it. In a non-interactive run (scripted, CI, eval) there is no later turn: stopping abandons the loop mid-round, so after launching, poll the task (TaskOutput with the returned task id, or sleep-and-recheck) until it completes, then relay the result. A session that answers "the loop is running, I'll report later" has lost the run.

使用Workflow工具运行，参数为

{scriptPath: "<步骤2获取的路径>", args: {...}}

：

json

{
  "target": "<仓库根目录>",
  "reviewer": {
    "kind": "skill",
    "name": "pr-review-toolkit:review-pr",
    "notes": "将工作树中的变更与<base>进行PR审查：检查正确性、测试用例、错误处理，以及该skill规定的其他审查维度。"
  },
  "scope": ["<推导的目录通配符>/**"],
  "pluginRoot": "<步骤2获取的插件目录>",
  "maxRounds": 5
}

```
reviewer
```
——上述默认配置需要
```
pr-review-toolkit
```
插件。若用户指定了其他PR审查器（skill或Agent），则使用该审查器并相应设置
```
kind
```
。
```
maxRounds
```
仅在用户要求不同上限时设置。
```
pluginRoot
```
用于让运行时找到指标收集器；仅当步骤2回退到使用工作流名称时才省略该参数——此时工作流会自行搜索自身路径。
```
finalize
```
的默认配置适用于PR：除非分支位于插件内，否则不进行版本升级，保留说明文档和传递检查结果。
```
decision
```
仅在后续续跑时设置（见下文）。

循环的基准快照是循环启动时的工作树——其范围防护机制会保护分支的未提交工作；审查器审查的是PR自身的提交内容。

工作流在后台运行，无需人工干预：它会执行审查、修复、重新审查，每次修复后检查范围，仅在审查无问题时才会完成。它不会自动提交变更，所有修改都保留在工作树中。

**若Workflow工具不可用或被拒绝，则终止并告知用户。**请勿直接通过编辑代码来模拟循环逻辑——台账、范围防护和升级保障都内置在工作流中，手动模拟无法实现这些功能。

**若结果为

halted: "reviewer-unavailable"

，则传达该信息并终止。**当前会话中未安装审查器；告知用户所需的插件（默认需要

pr-review-toolkit

），安装后重新运行。请勿自行审查分支。

**循环运行时请勿结束当前会话。**Workflow工具会立即返回任务ID，结果稍后返回。在交互式会话中，完成通知会重新调用您——请等待结果。在非交互式运行（脚本、CI、评估）中，没有后续会话：终止会导致循环中途停止，因此启动后需轮询任务（使用返回的任务ID调用TaskOutput，或定期检查）直至完成，然后传达结果。若会话回复“循环正在运行，稍后报告”则会丢失运行状态。

Relaying the result

传达结果

The workflow returns a structured result. Report it honestly — the distinctions matter:

converged: true
— the last action was a review with zero critical/major findings. Report rounds used, remaining minor findings (
```
open_minor_count
```
), and the artifact paths (
```
ledger_path
```
,
```
metrics
```
).
capped: true
— the fix budget ran out and the FINAL review still found blocking issues. Say plainly: capped, NOT converged, and list
```
open_blocking
```
. Do not present this as success.
escalation
— the loop detected it was not converging (recurring findings, non-decreasing counts, or a fix relocating a problem). Relay the escalation message and finding ids to the user: this needs a design decision, not more rounds.
halted
— a guard fired (scope violation, unregistered new files, a dead or unavailable reviewer, or a finalize pass whose own edits failed the check that follows it). Relay the paths in
```
violations
```
/
```
new_untracked_files
```
, the sites in
```
finalize_regressions
```
, and the notes.
notes
always travel with the result — surface them; they include loud warnings such as "a git repository was initialized".

工作流会返回结构化结果。请如实报告——不同结果的区别很重要：

converged: true
——最后一次审查无严重/主要问题。报告使用的循环次数、剩余的次要问题数量（
```
open_minor_count
```
）以及生成的文件路径（
```
ledger_path
```
,
```
metrics
```
）。
capped: true
——修复次数已达上限，且最后一次审查仍存在阻塞问题。明确告知：已达上限，未完成收敛，并列出
```
open_blocking
```
中的问题。请勿将此视为成功。
escalation
——循环检测到无法收敛（重复出现的问题、问题数量未减少，或修复导致问题转移）。将升级信息和问题ID传达给用户：这需要设计决策，而非更多循环次数。
halted
——触发了防护机制（范围违规、未注册的新文件、审查器不可用，或finalize阶段的修改未通过后续检查）。传达
```
violations
```
/
```
new_untracked_files
```
中的路径、
```
finalize_regressions
```
中的位置，以及备注信息。
**
```
notes
```
**始终随结果返回——请展示这些信息；其中包含诸如“已初始化git仓库”之类的重要警告。

Continuing after an escalation

升级后的续跑

The loop stops on escalation by design. When the user decides, start a fresh run with the same args plus:

json

{ "decision": "<the user's ruling, verbatim>" }

The new run reloads the on-disk ledger, so every finding, rejection, and verdict carries over — rounds restart, re-derivation does not.

To stop a running loop, stop the workflow task (TaskStop); the ledger on disk is current to the last round and a re-run resumes from it.

循环设计为触发升级时自动停止。当用户做出决策后，使用相同参数加上以下内容启动新的运行：

json

{ "decision": "<用户的决策原文>" }

新运行会重新加载磁盘上的台账，因此所有问题、拒绝记录和裁决都会保留——循环次数重新开始，无需重新推导范围。

如需停止正在运行的循环，可停止工作流任务（TaskStop）；磁盘上的台账会更新到最后一次循环的状态，重新运行时会从该状态恢复。

When NOT to use

不适用场景

One-time review: run the PR-review skill directly; the loop's value is iteration
A skill: use the
```
skill-improver
```
entry — it wires the right reviewer
Unpushed exploratory work: review-and-fix loops harden a diff; while the shape is fluid, manual iteration gives more control

一次性审查：直接运行PR-review skill即可；循环的价值在于迭代改进
Skill改进：使用
```
skill-improver
```
入口——它会连接合适的审查器
未推送的探索性工作：审查与修复循环会固化差异内容；当代码结构仍不稳定时，手动迭代能提供更多控制