solve-issue

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Solve Issue

解决Issue

Runs the full issue workflow in one command: analyze → branch → plan → implement → verify → tests audit → advisors → cleanup → commit → push/PR → review feedback → merge. Designed for issues the user already judged simple. When uncertainty appears, pause and ask rather than guess.

This skill owns engineering judgment only. Every git and

gh

write in the lifecycle — issue selection, branch, snapshot, commit, squash, push, PR, merge — is delegated to

issue-flow

, which owns them. The one write it does not own is the pull request's own review threads:

pr-review

posts and resolves those in Phase 7. Do not run a git or

gh

write command here yourself, and do not restate

issue-flow

's commit format or squash rules; read-only

git diff

git status

git log

gh pr view

for scoping and for seeing who is expected to review is fine.

通过一条命令运行完整的issue工作流：分析 → 创建分支 → 规划 → 实现 → 验证 → 测试审核 → 顾问审查 → 清理 → 提交 → 推送/PR → 审核反馈 → 合并。专为用户已判定为简单的issue设计。当出现不确定性时，暂停并询问用户而非自行猜测。

本技能仅负责工程判断。 生命周期中的每一项git和

gh

写入操作——issue选择、分支创建、快照、提交、压缩、推送、PR、合并——均由

issue-flow

负责处理。唯一不由它负责的是拉取请求自身的审核线程：

pr-review

会在第7阶段发布并解决这些线程。请勿在此自行运行git或

gh

写入命令，也不要重复

issue-flow

的提交格式或压缩规则；仅可运行只读的

git diff

git status

git log

gh pr view

命令来确定范围，以及查看预期的审核人员。

Conventions

约定

Asking the User

询问用户

Every question in this skill is written as

AskUserQuestion

options. Use that tool where the host offers it, or the host's nearest structured-choice equivalent. Where the host has neither, ask the same question in normal chat as a numbered list of 2–5 options — recommended first, one short line of description each — and wait for the user to reply with a number.

The endgame question in Phase 6 is never skipped. Every other gate defaults to proceeding, so a host that cannot prompt still completes the flow.

本技能中的每一个问题都以

AskUserQuestion

选项的形式编写。如果宿主提供该工具，则使用它；如果没有，则使用宿主最接近的结构化选择替代方案。如果两者都没有，则以普通聊天形式提出相同问题，列出2–5个编号选项——推荐选项放在首位，每个选项配一行简短描述——等待用户回复编号。

第6阶段的最终操作问题永远不会跳过。其他所有环节默认继续执行，因此无法提示的宿主仍可完成工作流。

Delegating to Other Skills

委托给其他技能

This skill is an orchestrator: it invokes

issue-flow

issue-analyze

changes-review

tests-audit

live-probe

code-cleanup

commit-summary

, and

pr-review

rather than reimplementing them. "Invoke

<name>

" means hand control to that skill however the host chains skills.

issue-flow
and
issue-analyze
are hard prerequisites. Every git and GitHub action in the flow lives in

issue-flow

, and the scope analysis it works from comes from

issue-analyze

; a host that cannot invoke another skill cannot run this one. Stop with

solve-issue needs to invoke issue-flow and issue-analyze; this host cannot chain skills.

rather than reimplementing the lifecycle inline. The rest —

changes-review

tests-audit

live-probe

code-cleanup

commit-summary

pr-review

— are graceful: each call site says what to do when that skill is missing.

本技能是一个编排器：它会调用

issue-flow

、

issue-analyze

、

changes-review

、

tests-audit

、

live-probe

、

code-cleanup

、

commit-summary

和

pr-review

，而非重新实现这些功能。 "调用

<name>

"指的是按照宿主的技能链方式将控制权交给该技能。

issue-flow
和
issue-analyze
是硬性前置条件。工作流中的每一项git和GitHub操作都由

issue-flow

处理，其依赖的范围分析来自

issue-analyze

；无法调用其他技能的宿主无法运行本技能。此时应停止并提示

solve-issue needs to invoke issue-flow and issue-analyze; this host cannot chain skills.

，而非尝试内联重新实现生命周期。其余技能——

changes-review

、

tests-audit

、

live-probe

、

code-cleanup

、

commit-summary

、

pr-review

——是可选的：每个调用点都说明了当该技能缺失时的处理方式。

Tracking Progress

跟踪进度

Where the host has a task list, put one entry per Changes item in it and update entries as you go. Where it does not, keep the printed numbered Changes list as the tracker and state which item you are on before starting it. Either way, progress is visible per item — never a single opaque "implementing" step.

如果宿主有任务列表，则在其中为每个变更项添加一个条目，并在执行过程中更新条目状态。如果没有，则保留打印的编号变更列表作为跟踪器，并在开始每个项之前说明当前正在处理哪一项。无论哪种方式，都要按项展示进度——绝不能只有一个模糊的“正在实现”步骤。

Flow Overview

工作流概述

Phase	Step	Asks user?
0	Resolve issue number	Only if `$ARGUMENTS` is empty
1	Analyze via `issue-analyze`	No
2	Plan + create branch	Only if plan is genuinely uncertain
3	Implement	Only on hard blockers
4	Verify (checks + optional probe)	Only to opt into a live observation
4.4	Subtle simplification pass	No
4.5	Tests audit (only if tests moved)	No
4.6	Advisor round(s) + apply fixes	No
5	Comment cleanup + commit	No
6	Summary + choose endgame	Always — 4 options via AskUserQuestion
7	Review feedback, then merge	Through `pr-review` 's own gate

阶段	步骤	是否询问用户？
0	确定issue编号	仅当 `$ARGUMENTS` 为空时
1	通过 `issue-analyze` 进行分析	否
2	规划 + 创建分支	仅当规划存在真正的不确定性时
3	实现	仅遇到严重障碍时
4	验证（检查 + 可选探测）	仅询问是否选择实时观测
4.4	细微简化处理	否
4.5	测试审核（仅当测试文件被修改时）	否
4.6	顾问审查轮次 + 应用修复	否
5	清理注释 + 提交	否
6	总结 + 选择最终操作	是——通过AskUserQuestion提供4个选项
7	处理审核反馈，然后合并	通过 `pr-review` 自身的环节进行询问

Phase 0: Resolve Issue

阶段0：确定Issue

$ARGUMENTS

holds an issue number or GitHub issue URL, use it directly and skip to Phase 1.

If empty, ask via

AskUserQuestion

question: "No issue number provided. How should I pick one?"

Option 1 — header

Next issue

, label

Let issue-flow pick

(Recommended)

—

Rank the backlog and recommend the most relevant open issue.

Option 2 — header

Manual

, label

Stop and ask

—

Exit so you can re-run with an explicit issue number.

Option 1 → invoke
```
issue-flow
```
with intent
```
"pick an issue"
```
. Its Step 0 ranks the backlog, lets the user choose, and chains into
```
issue-analyze
```
on the selection — continue from Phase 2 with the number and the analysis it returns. Two outcomes are not a selection: the user picks
```
None
```
, or the branch it short-circuited on carries no issue number. Both end the run — stop and say which. Phase 5 commits under the issue title, so never continue without one.

Option 2 → print

Re-run with an issue number, e.g. /solve-issue 42.

and stop.

如果

$ARGUMENTS

包含issue编号或GitHub issue URL，直接使用并跳至阶段1。

如果为空，则通过

AskUserQuestion

询问：

问题："未提供issue编号。应如何选择？"

选项1 — 标题

下一个issue

，标签

由issue-flow选择

(推荐)

—

对积压任务排序，推荐最相关的开放issue。

选项2 — 标题

手动选择

，标签

停止并询问

—

退出，以便你重新运行时指定明确的issue编号。

选项1 → 调用
```
issue-flow
```
，意图为
```
"pick an issue"
```
。其步骤0会对积压任务排序，让用户选择，并在选中后调用
```
issue-analyze
```
——使用返回的编号和分析结果从阶段2继续。两种情况不属于选择：用户选择
```
None
```
，或短路分支未携带issue编号。这两种情况都会终止运行——停止并说明原因。阶段5会以issue标题提交，因此绝不能在没有编号的情况下继续。

选项2 → 打印

Re-run with an issue number, e.g. /solve-issue 42.

并停止。

Phase 1: Analyze

阶段1：分析

Invoke

issue-analyze

<N>

. Do not duplicate its work inline — capture the Scope Analysis and Implementation Tasks it emits. It is a prerequisite, not a nice-to-have: it resolves the issue title this flow commits under, and the blockers Phase 1 stops on.

Stop conditions from the analyzer:

Issue is closed → print its status line and stop.
Issue has an open blocker → print the blocker and stop. Do not implement through an open blocker without explicit user approval.
Issue is assigned to another user (
```
> Note:
```
line) → continue, but flag the condition in the final summary.

对

<N>

调用

issue-analyze

。请勿内联重复其工作——捕获它输出的范围分析和实现任务。这是必备条件，而非可选功能：它会解析本工作流用于提交的issue标题，以及阶段1需要停止的障碍。

来自分析器的停止条件：

Issue已关闭 → 打印其状态行并停止。
Issue存在未解决的障碍 → 打印障碍并停止。未经用户明确批准，请勿绕过未解决的障碍进行实现。
Issue已分配给其他用户（
```
> Note:
```
行） → 继续执行，但在最终总结中标记该情况。

Phase 2: Plan

阶段2：规划

Produce a structured plan before any implementation, in the same shape Plan mode produces — goal, file-level change list, explicit out-of-scope, risks or decisions. Do not write a plan file; print the plan inline only.

Before drafting, do enough read-only investigation to make the plan file-specific (Read, Grep, Glob). Do not edit anything yet.

在开始任何实现之前生成结构化规划，格式与规划模式生成的一致——目标、文件级变更列表、明确的范围外内容、风险或决策。请勿编写规划文件；仅内联打印规划内容。

在起草之前，进行足够的只读调查，使规划具体到文件层面（读取、Grep、Glob）。请勿编辑任何内容。

Plan output format

规划输出格式

Print the plan inline, in the exact structure

references/plan-format.md

specifies — goal, numbered file-level Changes, explicit out-of-scope, risks or decisions. That file also carries the rules the body has to satisfy. Do not write a plan file.

After printing the plan, set up progress tracking per Conventions → Tracking Progress — one entry per Changes item.

内联打印规划，严格遵循

references/plan-format.md

指定的结构——目标、编号的文件级变更、明确的范围外内容、风险或决策。该文件还规定了规划内容必须满足的规则。请勿编写规划文件。

打印规划后，按照约定 → 跟踪进度设置进度跟踪——为每个变更项创建一个条目。

When to pause for approval

何时暂停等待批准

Default: proceed to Phase 3 immediately after printing the plan. The printed plan is the checkpoint, and the user can interrupt if they disagree — do not ask for approval on a simple issue.

references/plan-format.md

lists the five conditions that override that default and the shape of the one question to ask when any of them fires.

默认：打印规划后立即进入阶段3。打印的规划是检查点，如果用户不同意可以中断——对于简单issue，请勿请求批准。

references/plan-format.md

列出了5种覆盖默认设置的条件，以及触发这些条件时应提出的问题格式。

Create branch

创建分支

Invoke

issue-flow

with intent

"start work on #<N>"

. That runs its Step 2, which checks out

issue-<N>

off the correct base branch and updates the project board to "In Progress" when available.

issue-<N>

already exists, let

issue-flow

handle the switch-vs-recreate prompt.

Record the

Fork:

SHA from its Step 2 report — later phases diff against it to scope verification and pass it to the reviewers. Use

Fork:

, not

Base:

Base:

is a branch name, and an epic branch that exists only on the remote fails in

git diff <name>..HEAD

with

unknown revision

. A SHA always resolves.

Every phase that scopes by the fork reads the working tree, never
<fork>..HEAD
. Snapshots are optional until Phase 4.6, so on a run that never took one

HEAD

still is the fork and that range is empty while the changes sit unstaged — which would silently scope a phase to nothing. The form is

git diff --name-only <fork>

plus

git ls-files --others --exclude-standard

, and it is stated here once so no phase or reference has to restate it.

Do not detect the base yourself;

issue-flow

owns base detection, and its

detect-base.sh

handles the

epic-*

cases a naive

origin/HEAD

lookup gets wrong. If the flow was entered on an existing branch and no Step 2 report was printed, ask

issue-flow

for the fork point.

调用

issue-flow

，意图为

"start work on #<N>"

。这会运行其步骤2，从正确的基础分支检出

issue-<N>

，并在可用时将项目看板更新为"进行中"。

如果

issue-<N>

已存在，让

issue-flow

处理切换与重建的提示。

记录其步骤2报告中的

Fork:

SHA——后续阶段会以此为基准进行差异对比，确定验证范围，并将其传递给审核人员。使用

Fork:

而非

Base:

：

Base:

是分支名称，仅存在于远程的史诗分支在

git diff <name>..HEAD

中会因

unknown revision

失败。SHA始终可以解析。

所有基于分叉确定范围的阶段都读取工作树，而非
<fork>..HEAD
。在阶段4.6之前快照是可选的，因此在从未拍摄快照的运行中，

HEAD

仍然是分叉，该范围为空，而变更处于未暂存状态——这会导致某个阶段的范围被静默设置为空。正确的形式是

git diff --name-only <fork>

加上

git ls-files --others --exclude-standard

，此处仅说明一次，后续阶段和参考文档无需重复。

请勿自行检测基础分支；

issue-flow

负责基础分支检测，其

detect-base.sh

会处理

epic-*

情况，而简单的

origin/HEAD

查找无法正确处理这些情况。如果工作流是在现有分支上启动的，且未打印步骤2报告，请向

issue-flow

询问分叉点。

Phase 3: Implement

阶段3：实现

Work through the tracked Changes items sequentially. Mark each one started when you begin it and done as soon as it is done — no batching.

For a checkpoint mid-implementation, invoke

issue-flow

with intent

"snapshot"

— its Step 3 snapshot mode freezes the tree into a content-free

wip:

commit. Phase 5 squashes those away. Do not push between tasks.

If a task hits a hard blocker (missing credentials, external service down, decision required), stop and ask the user.

按顺序处理跟踪的变更项。开始处理时标记为“已启动”，完成后立即标记为“已完成”——请勿批量处理。

如需在实现中途创建检查点，调用

issue-flow

，意图为

"snapshot"

——其步骤3的快照模式会将工作树冻结为无内容的

wip:

提交。阶段5会将这些提交压缩合并。请勿在任务之间推送。

如果任务遇到严重障碍（缺少凭据、外部服务宕机、需要决策），停止并询问用户。

Phase 4: Verify

阶段4：验证

Detect the verification set from

package.json

+ repo conventions. Do not skip verification on "simple" changes.

从

package.json

和仓库约定中检测验证集。请勿因变更“简单”而跳过验证。

Choosing what to run

选择要运行的内容

references/verification-set.md

has the script groups, the runner-from-lockfile rule, and which groups the changed file set selects. Scope it with the

Fork:

SHA recorded in Phase 2, not a branch name.

references/verification-set.md

包含脚本组、从锁定文件选择运行器的规则，以及变更文件集对应的组。使用阶段2记录的

Fork:

SHA确定范围，而非分支名称。

Observe it running (opt-in)

观测运行过程（可选）

Checks prove the change compiles and that nothing already covered broke. They do not prove a claim about observable output — layout, rendering, wire format, exit code, timing, log content, a golden result. Where the issue asked for a change of that kind, ask, per Asking the User:

Option 1 — header

Skip probe

, label

Skip observation

(Recommended)

—

Checks cover this scope.

Option 2 — header

Observe

, label

Run and observe

—

Run it the way this project declares and read the result.

On opt-in, invoke

live-probe

with the behavior the issue asked for. It reads the project's declared way to run and observe from the instruction layer first (

CLAUDE.md

AGENTS.md

, rules files), then the repo's declared commands, and reports

unverified

rather than inventing one. Expect one such tool, not a matched pair. Where the host cannot chain skills, follow the same method inline.

Starting things is slow and leaves an artifact to clean up, so the default is to skip.

检查可证明变更可编译且现有功能未被破坏，但无法证明关于可观测输出的声明——布局、渲染、 wire格式、退出码、时序、日志内容、标准结果。如果issue要求进行此类变更，请按照询问用户的方式询问：

选项1 — 标题

跳过探测

，标签

跳过观测

(推荐)

—

检查已覆盖此范围。

选项2 — 标题

观测

，标签

运行并观测

—

按照项目声明的方式运行并读取结果。

如果用户选择观测，调用

live-probe

，传入issue要求的行为。它会首先从指令层（

CLAUDE.md

、

AGENTS.md

、规则文件）读取项目声明的运行和观测方式，然后读取仓库声明的命令，如果无法找到则报告

unverified

，而非自行创建。预期仅调用一个此类工具，而非一对匹配工具。如果宿主无法进行技能链调用，请内联遵循相同方法。

启动过程较慢且会留下需要清理的工件，因此默认跳过。

On failure

失败处理

If any verification step fails:

Go back to Phase 3, fix the cause, and re-run only the failing check.
If the same check fails twice after two fix attempts, stop and hand back to the user with the failure output. Do not proceed past Phase 4 with failing verification. Do not rationalize skipping it.

如果任何验证步骤失败：

返回阶段3，修复问题原因，然后仅重新运行失败的检查。
如果两次修复尝试后同一检查仍失败，停止并将失败输出交还给用户。验证失败时请勿进入阶段4。请勿找理由跳过验证。

Phase 4.4: Simplify

阶段4.4：简化

Run this before the advisor round, so the reviewers attack the code that will actually ship. A simplification applied after review ships unreviewed.

Dispatch one subagent over the changed files with a single instruction: apply subtle, behavior-preserving simplifications against the bar below, and nothing else. If the host has no subagent facility, run the same instruction inline.

在顾问审查轮次之前运行此步骤，以便审核人员审查的是实际会发布的代码。审核后应用的简化变更将不会被审查。

为变更文件分配一个子代理，仅执行一条指令：根据以下标准应用细微的、不改变行为的简化，不进行其他操作。如果宿主没有子代理功能，请内联执行相同指令。

The simplification bar

简化标准

Apply only when all hold:

Behavior is provably unchanged
The change is contained to a single function or a local symbol
No public export, API shape, or file layout is touched
It makes the code shorter and clearer, not merely shorter

Anything heavier — splitting functions, reshaping control flow, extracting utilities, renaming exported symbols — is not applied. Record it for the Phase 6 summary and move on: a refactor that is merely nice is out of scope for an issue the user called simple.

Re-run the Phase 4 checks the simplifications could plausibly break. Revert anything that fails rather than fixing around it — behavior-preserving was the bar, and a failing check is proof it was not met.

仅当所有以下条件都满足时才应用简化：

行为可证明未改变
变更仅限于单个函数或局部符号
未触及公共导出、API形状或文件布局
代码更短且更清晰，而非仅仅更短

任何更复杂的操作——拆分函数、重构控制流、提取工具、重命名导出符号——都不允许应用。将其记录到阶段6的总结中并继续：对于用户认定为简单的issue，仅为优化而进行的重构超出范围。

重新运行简化可能影响的阶段4检查。如果失败则回滚简化——不改变行为是标准，检查失败证明未满足该标准。

Phase 4.5: Tests Audit

阶段4.5：测试审核

Take the changed test files from the working tree, per Phase 2 → Create branch. Skip this phase only when that set carries no test file.

Otherwise dispatch a subagent to run

tests-audit

over those files, and give it the code under test and nothing else — not the Phase 2 plan, not what you were trying to do, not why you wrote the tests that way. Its gate asks which promise each test pins and what dumbest implementation still passes it, so it needs the source; your justification is the one thing that would let a weak test through. Where the host has no subagent facility, run it inline under the same restriction. It runs before the advisor round for the reason Phase 4.4 does: a test rewritten after review ships unreviewed, and it earns its place beside those reviewers by running the suite — order dependence and flakiness are invisible to anyone only reading the diff.

tests-audit

reports and never edits, so applying its verdicts is this phase's job.

references/tests-audit-pass.md

has which verdicts to apply against a test this branch wrote versus one it merely lives beside, and the gate to run inline when the skill is not installed.

The rule that never bends: a tightened assert that now fails is either the defect the loose one was hiding — fix it, that is the payoff — or a bad tightening, in which case revert that assert. Never loosen it back to make the suite green.

从工作树中获取变更的测试文件，遵循阶段2 → 创建分支的规则。仅当该集合中没有测试文件时才跳过此阶段。

否则分配子代理对这些文件运行

tests-audit

，仅提供被测代码——不提供阶段2的规划、实现意图、编写测试的原因。它会检查每个测试所验证的承诺，以及仍能通过测试的最简陋实现，因此需要源代码；你的理由会让薄弱的测试通过。如果宿主没有子代理功能，请内联执行相同操作。在顾问审查轮次之前运行此步骤，原因与阶段4.4相同：审核后重写的测试将不会被审查，且它通过运行测试套件获得与审核人员同等的地位——仅查看差异无法发现顺序依赖和不稳定问题。

tests-audit

仅报告不编辑，因此应用其结论是此阶段的任务。

references/tests-audit-pass.md

规定了针对本分支编写的测试与仅相邻的测试应应用哪些结论，以及未安装该技能时内联运行的检查规则。

不可动摇的规则：如果收紧断言后测试失败，要么是宽松断言隐藏的缺陷——修复它，这就是收益——要么是错误的收紧，此时应回滚该断言。绝不能放宽断言使测试套件通过。

Phase 4.6: Advisor Round

阶段4.6：顾问审查轮次

Independent reviewers attack the change in parallel, then their findings are triaged and fixed. This always runs once verification is green — it is the polish pass, not an optional extra.

The review itself belongs to

changes-review

. This phase owns only what is workflow policy: freezing the diff, triaging findings, and deciding whether to run a second round. Do not duplicate the reviewer prompts here, and do not invoke

consilium

— that board ranks candidate approaches to a problem and has nothing to say about whether a finished diff is correct.

独立审核人员并行审查变更，然后对发现的问题进行分类和修复。验证通过后始终运行此步骤——这是优化步骤，而非可选操作。

审查本身由

changes-review

负责。此阶段仅负责工作流策略：冻结差异、分类发现的问题、决定是否运行第二轮审查。请勿在此重复审核人员的提示，也不要调用

consilium

——该工具用于对问题的候选解决方案排序，与已完成的差异是否正确无关。

Freeze the diff first

先冻结差异

Every reviewer must see the same change set. Before dispatching, delete the cruft listed under Phase 5 → Remove cruft — the snapshot stages everything, so scratch files and screenshots would otherwise be baked in where Phase 5's untracked-file check can no longer see them.

Then, if the tree is dirty, invoke

issue-flow

with intent

"snapshot"

. Its Step 3 snapshot mode stages the tree and commits it under a content-free

wip:

subject. Phase 5 squashes it away.

Each round freezes again — round 2 must snapshot the round-1 fixes before dispatching, or the reviewers re-review the diff they already saw. Round 2 and later also pass

--mode simple

with the previous round's snapshot as the base, so the reviewers attack the fix rather than re-reading the whole branch to check a two-line change.

Carry your own list of findings you accepted rather than fixed. The reviewers are blind to previous rounds by design, so an accepted decision comes back every round — recognizing it is your job, not theirs.

每个审核人员必须看到相同的变更集。在分配任务之前，删除阶段5 → 清理无用内容中列出的无用文件——快照会暂存所有内容，因此临时文件和截图会被固化，而阶段5的未跟踪文件检查无法再检测到它们。

然后，如果工作树有未提交的变更，调用

issue-flow

，意图为

"snapshot"

。其步骤3的快照模式会暂存工作树，并以无内容的

wip:

主题提交。阶段5会将这些提交压缩合并。

每一轮审查都要重新冻结差异——第二轮必须在分配任务前对第一轮的修复进行快照，否则审核人员会重新审查他们已经看过的差异。第二轮及后续轮次还要传入

--mode simple

，并以上一轮的快照为基准，以便审核人员审查修复内容，而非重新读取整个分支来检查两行变更。

自行记录已接受但未修复的问题列表。审核人员默认不知道之前的轮次，因此已接受的决策每一轮都会被提出——识别这些决策是你的工作，而非审核人员的。

Run the review

运行审查

Invoke

changes-review

with

--base <fork>

and

--issue <N>

, using the

Fork:

SHA recorded in Phase 2 — it resolves as a rev where a branch name may not. It dispatches the reviewers, re-attacks its own findings — verification is on by default for a

--base

run — and returns what survives. It changes nothing.

Pass no other context. Not the Phase 2 plan, not the Risks/decisions section, not a summary of what you were trying to do, not the previous round's findings or how you triaged them. The skill's entire value is that its reviewers are blind to your reasoning; handing it a summary destroys that.

调用

changes-review

，传入

--base <fork>

和

--issue <N>

，使用阶段2记录的

Fork:

SHA——它可以解析为版本，而分支名称可能无法解析。它会分配审核人员，重新检查自身发现的问题——

--base

运行默认启用验证——并返回留存的问题。它不会修改任何内容。

不要传入其他任何上下文。不要传入阶段2的规划、风险/决策部分、实现意图的总结、上一轮的发现或分类方式。该技能的全部价值在于其审核人员不知道你的推理过程；传入总结会破坏这一点。

Triage and fix

分类和修复

Classify every returned finding:

Class	Meaning	Action
Fix	Real defect or a genuine requirement gap	Apply now
Note	Valid but out of scope for this issue	Report in Phase 6
Reject	Wrong, or the reviewer lacked context that makes the code correct	Report in Phase 6

Rules that keep triage honest — you are judging reviews of your own work, and the pull toward dismissal is real:

Uncertainty defaults to Fix. If you cannot show a finding is wrong, it is not rejected.
A Reject must name the specific context the reviewer lacked — the file it could not see, the invariant it did not know. "I don't think that's right" is not a rejection.
Rejects survive verbatim. Phase 6 carries the reviewer's own wording, not your paraphrase of it. The user grades the rejection, not your summary.

Apply the Fix items, then re-run the Phase 4 checks the fixes could plausibly break. Verification must be green again before continuing.

对每个返回的问题进行分类：

类别	含义	操作
修复	真正的缺陷或实际的需求缺口	立即应用修复
备注	有效但超出当前issue的范围	在阶段6报告
拒绝	错误，或审核人员缺少使代码正确的上下文	在阶段6报告

保持分类公正的规则——你在评判自己工作的审核结果，倾向于驳回的可能性是真实存在的：

不确定性默认归为修复。如果你无法证明某个问题是错误的，则不能拒绝。
拒绝必须指明审核人员缺少的具体上下文——它看不到的文件、不知道的不变量。"我认为不对"不是拒绝。
拒绝内容原样保留。阶段6要保留审核人员的原话，而非你的转述。用户会评判拒绝是否合理，而非你的总结。

应用修复项，然后重新运行修复可能影响的阶段4检查。继续之前必须再次通过验证。

Round 2

第二轮审查

Run a second round if any of these hold:

The fixes touched a file that was not in the round-1 diff
The fixes changed more than ~30% of the round-1 changed-line count
You rejected any intent-reviewer finding
You rejected more than half of all findings

The last two matter because rejects do not change the diff, so a wrongly rejected bug is invisible to a size-based trigger. A high reject rate is the signal that the implementer is grading itself generously.

Otherwise stop at one round. Hard cap: two rounds. If round 2 surfaces another large batch, do not run a third — apply the clear fixes, list the rest as Notes, and let the PR review catch them.

如果任意以下条件满足，运行第二轮审查：

修复修改了第一轮差异中未包含的文件
修复修改了第一轮变更行数的约30%以上
你拒绝了任何意图审核人员的问题
你拒绝了超过一半的所有问题

最后两个条件很重要，因为拒绝不会改变差异，因此错误拒绝的bug无法通过基于大小的触发机制检测到。高拒绝率表明实现者对自己的评价过于宽松。

否则停止于一轮审查。硬限制：两轮。如果第二轮又出现大量问题，不要运行第三轮——应用明确的修复，将其余问题列为备注，让PR审核来发现它们。

Phase 5: Cleanup + Commit

阶段5：清理 + 提交

Trim comments

精简注释

Invoke

code-cleanup --comments-only

, scoped to the change. This is the step that stops verbose AI commentary from reaching the commit: it removes comments that restate the code, compacts genuine gotchas to a line or two, and surfaces design rationale for the commit body.

--comments-only

is deliberate — no code changes at commit time. Any simplification opportunity belongs to Phase 4.6, where it was reviewed. If

code-cleanup

reports suggested refactors, carry them into the Phase 6 summary as Notes; do not apply them here.

Its Suggested for commit message section is an input to the commit body — it answers why the code is built the way it is, which is the first thing the body has to establish. Pass it along under Commit below;

issue-flow

folds it into that paragraph rather than tacking it on at the end.

code-cleanup

is not installed, do the comment pass inline, and be aggressive: delete comments that narrate what the code already says, that repeat what a nearby comment already carries, or that point at an issue or PR instead of stating the fact. Keep non-obvious gotchas at one to two lines. Leave documentation comments and

HACK

FIXME

TODO

markers alone.

调用

code-cleanup --comments-only

，范围限定为变更内容。这一步会阻止冗长的AI注释进入提交：它会删除重复代码逻辑的注释，将真正的陷阱压缩为一两行，并为提交正文提取设计依据。

--comments-only

是刻意设置的——提交时不进行任何代码变更。任何简化机会都属于阶段4.6，在那里会被审查。如果

code-cleanup

报告建议重构，将其作为备注带入阶段6的总结；请勿在此应用。

其提交消息建议部分是提交正文的输入——它解释了代码为何如此构建，这是提交正文必须首先说明的内容。将其传递给下面的提交步骤；

issue-flow

会将其融入段落，而非附加在末尾。

如果未安装

code-cleanup

，请内联执行注释清理，且要严格：删除重复代码逻辑的注释、重复附近注释内容的注释、指向issue或PR而非说明事实的注释。将非显而易见的陷阱保留为一两行。保留文档注释和

HACK

FIXME

TODO

标记。

Remove cruft

清理无用内容

Delete anything that should not ship with the commit:

Plan and scratch files under
```
.claude/plans/
```
,
```
.claude/plan/
```
, or
```
docs/superpowers/
```
— gitignored working artifacts, per the repo's instructions file. Only files this run created; never a config directory.
Temp files under
```
tmp/
```
or
```
.tmp/
```
at the repo root that were created during this run
Captured probe artifacts — screenshots, traces, dumps — wherever the instruction layer puts them, if they were throwaway

Use

git status --short

to sanity-check that no untracked scratch files are about to be staged, and that every intended deletion shows up.

删除任何不应随提交发布的内容：

```
.claude/plans/
```
、
```
.claude/plan/
```
或
```
docs/superpowers/
```
下的规划和临时文件——根据仓库的指令文件，这些是被git忽略的工作工件。仅删除本次运行创建的文件；绝不要删除配置目录。
仓库根目录下
```
tmp/
```
或
```
.tmp/
```
中本次运行创建的临时文件
捕获的探测工件——截图、跟踪记录、转储文件——无论指令层将其放在何处，如果是一次性的则删除

使用

git status --short

进行检查，确保没有未跟踪的临时文件即将被暂存，且所有预期删除的文件都已显示。

Commit

提交

Invoke

issue-flow

with intent

"commit #<N>"

. Its Step 3 squashes the branch to one commit, writes the subject and body, and reports the result. It owns the commit subject format, the body, and the squash rules for every

wip:

snapshot Phase 4.6 created — do not restate any of them here, and do not run the git commands yourself.

Pass along, as context for the commit body:

The issue title and number, so the subject can be built.
The design rationale
```
code-cleanup
```
pulled out of the source, if it produced any — that text is why the comment pass could delete it, and it answers the body's first question. It is not a block to append at the end.

Capture the short SHA and subject from Step 3's report for the Phase 6 summary. If Step 3 comes back with a dirty tree or more than one commit, that is a failure of the commit step — re-invoke it rather than fixing the history here. The endgame pushes the commit, not the working copy.

调用

issue-flow

，意图为

"commit #<N>"

。其步骤3会将分支压缩为一个提交，编写主题和正文，并报告结果。它负责提交主题格式、正文，以及阶段4.6创建的所有

wip:

快照的压缩规则——请勿在此重复这些规则，也不要自行运行git命令。

为提交正文传递以下上下文：

issue标题和编号，以便构建提交主题。
```
code-cleanup
```
从源代码中提取的设计依据（如果有的话）——这段文本是注释清理可以删除它的原因，它回答了提交正文的第一个问题。不要将其作为块附加在末尾。

从步骤3的报告中捕获短SHA和主题，用于阶段6的总结。如果步骤3返回工作树有未提交变更或多个提交，说明提交步骤失败——重新调用它，而非在此修复历史记录。最终操作推送的是提交，而非工作副本。

Phase 6: Summary + Endgame

阶段6：总结 + 最终操作

Print the compact summary

references/report-format.md

specifies — what changed, what was verified, what the tests audit moved, what the advisors found, and the commit.

Never omit a Reject: a rejected finding the user never sees is the one failure mode this whole phase is built to prevent, and Phase 4.6 requires the reviewer's own wording.

Then ask via

AskUserQuestion

question: "What's next for this commit?"

Option 1 — header

PR + merge

, label

Push, PR, auto-merge

(Recommended)

—

Push, open a PR, answer the automated reviewers, merge once no reviewer is left unresolved.

Option 2 — header

PR only

, label

Push and open PR

—

Push, open a PR, answer any review already in, stop before merge.

Option 3 — header

Push only

, label

Push the branch

—

Push the branch. No PR.

Option 4 — header

Nothing

, label

Leave it local

—

Keep the commit local. No push.

Route via

issue-flow

Choice	`issue-flow` intent	Then
PR + merge	`"push and open PR for #<N>"` — Steps 4 and 5	Phase 7, then Step 6 merge
PR only	`"push and open PR for #<N>"` — Steps 4 and 5	Phase 7, then stop
Push only	`"push #<N>"` — Step 4	Stop
Nothing	Stop — commit stays local	—

The merge is not part of the endgame invocation.

PR + merge

opens the pull request, hands to Phase 7, and merges only after the automated reviewers have had their window. Asking

issue-flow

for

"push, PR, and merge"

in one intent merges past them.

Let

issue-flow

handle the per-step questions it already owns (squash confirmation, reviewer selection, merge pre-checks). Do not duplicate those prompts here.

打印

references/report-format.md

指定的简洁总结——变更内容、验证情况、测试审核的修改、顾问发现的问题，以及提交信息。

绝不要省略拒绝内容：用户从未看到的被拒绝问题是整个阶段要防止的失败模式，阶段4.6要求保留审核人员的原话。

然后通过

AskUserQuestion

询问：

问题："此提交下一步如何处理？"

选项1 — 标题

PR + 合并

，标签

推送、创建PR、自动合并

(推荐)

—

推送代码、创建PR、回复自动化审核人员、待所有审核人员问题解决后合并。

选项2 — 标题

仅创建PR

，标签

推送并创建PR

—

推送代码、创建PR、回复已有的审核问题、合并前停止。

选项3 — 标题

仅推送

，标签

推送分支

—

推送分支。不创建PR。

选项4 — 标题

不操作

，标签

保留在本地

—

将提交保留在本地。不推送。

通过

issue-flow

路由：

选择	`issue-flow` 意图	后续操作
PR + 合并	`"push and open PR for #<N>"` — 步骤4和5	阶段7，然后步骤6合并
仅创建PR	`"push and open PR for #<N>"` — 步骤4和5	阶段7，然后停止
仅推送	`"push #<N>"` — 步骤4	停止
不操作	停止——提交保留在本地	—

合并不属于最终操作调用的一部分。

PR + 合并

会创建拉取请求，进入阶段7，仅在自动化审核人员完成反馈后才合并。向

issue-flow

请求

"push, PR, and merge"

会绕过审核人员直接合并。

让

issue-flow

处理它已经负责的每一步问题（压缩确认、审核人员选择、合并预检查）。请勿在此重复这些提示。

Do not stop at "PR created"

不要在"PR已创建"时停止

Both PR endgames end with a mergeability verdict, not just a PR URL.

issue-flow

Step 5 produces a

Mergeable:

line — report it. Do not claim a pull request is ready without it, and if it comes back

CONFLICTING

the flow is not done: rebase, force-push, re-check, report the resolved state.

Neither path is finished at Step 5 either. Both continue into Phase 7.

两种PR最终操作都以可合并性结论结束，而非仅返回PR URL。

issue-flow

步骤5会生成

Mergeable:

行——报告该内容。不要在没有该内容的情况下声称拉取请求已准备就绪，如果返回

CONFLICTING

，工作流尚未完成：重新变基、强制推送、重新检查、报告解决后的状态。

两种路径在步骤5后都未完成，都会进入阶段7。

Phase 7: Review Feedback

阶段7：处理审核反馈

Runs on both PR endgames. Skipped for

Push only

and

Nothing

Detect, then decide whether waiting buys anything. One read of the pull request's requested reviewers and its latest reviews, plus a single ~20s confirm, separates "still working" from "already reported" from "nobody is coming". The confirm is not optional: a request landing three seconds late otherwise prints as

No automated reviewers

, which is a wrong report rather than a saved wait. A review already in is worked on either endgame. Only

PR + merge

ever polls — on

PR only

nothing downstream consumes the answer, so a pending bot is reported as pending and the flow stops.

On the merge path
no / no
means unknown, not nobody. That a pending bot sits in the requested list is inferred, not observed, so keep polling until the CI wait resolves — free, since it overlaps CI — and never merge with a bot unresolved. A bot that appears in the latest reviews having never appeared as requested disproves the table: say so in the report and stop trusting it.

references/review-feedback.md

has the query, the table, the budget, and why checks are the wrong place to look.

Then invoke

pr-review <N> --fix

, which owns the step: author-side standing, verifying each claim's premise separately from its conclusion, the six verdicts, the reply, the resolve. Do not re-triage its findings or restate its rules. On

PR + merge

add

--auto

— which posts unattended on bot-rooted threads only, holding any human thread as an unsent draft — plus the instruction to publish nothing until the fixes are pushed, since a reply naming a landed fix is false the moment it posts otherwise and its thread is then resolved on a claim that never became true. The order is fix, check, push, publish.

Code that

--fix

applied is uncommitted work on the squashed commit. It runs the project's checks per fix, so re-run only the wider Phase 4 set once over the final tree, then invoke

issue-flow

with intent

"amend and push #<N>"

, keeping the message verbatim. Skip the amend when nothing changed: an all-

reject

round would force-push an identical tree, re-trigger CI and the reviewers, and buy a second round for nothing.

Amending re-triggers a repository configured to request review automatically, so run the detection again after the push and let it decide. Run this phase at most twice.

在两种PR最终操作中运行。

仅推送

和

不操作

会跳过此阶段。

先检测，再判断等待是否有意义。 读取一次拉取请求的指定审核人员和最新审核结果，加上约20秒的确认，即可区分"仍在处理"、"已反馈"和"无人响应"。确认是必须的：否则三秒后到达的请求会被报告为"无自动化审核人员"，这是错误报告而非节省等待时间。已有的审核问题在两种最终操作中都会处理。仅

PR + 合并

会轮询——

仅创建PR

中没有下游环节需要结果，因此待处理的机器人会被报告为待处理，工作流停止。

在合并路径中，"无/无"表示未知，而非无人响应。 待处理的机器人在指定列表中是推断的，而非观测到的，因此要持续轮询直到CI等待结束——这是免费的，因为与CI重叠——绝不要在机器人未解决时合并。如果某个机器人从未出现在指定列表中，但出现在最新审核结果中，则证明检测表格错误：在报告中说明并停止信任它。

references/review-feedback.md

包含查询方式、表格、时间预算，以及为何检查不是正确的查看位置。

然后调用

pr-review <N> --fix

，它负责此步骤：作者立场、分别验证每个声明的前提和结论、六种结论、回复、解决。请勿重新分类其发现的问题或重复其规则。在

PR + 合并

中添加

--auto

——仅针对机器人发起的线程自动回复，将人工线程保留为未发送草稿——加上修复推送前不发布任何内容的指令，否则提及已落地修复的回复在发布时就是错误的，其线程会基于从未成立的声明被解决。顺序是修复、检查、推送、发布。

--fix

应用的代码是压缩提交上的未提交工作。它会在每次修复后运行项目的检查，因此仅需对最终工作树重新运行一次更广泛的阶段4检查，然后调用

issue-flow

，意图为

"amend and push #<N>"

，保持消息不变。如果没有变更则跳过修正：全拒绝的轮次会强制推送相同的工作树，重新触发CI和审核人员，毫无意义地进行第二轮审查。

修正会触发配置为自动请求审核的仓库，因此推送后重新运行检测并让它决定。此阶段最多运行两次。

Report and close

报告并结束

Append the Review feedback block

references/report-format.md

specifies — including what the fixes changed, because the merge ships code the Phase 6 summary did not describe — then close the endgame:

PR + merge — invoke
```
issue-flow
```
with intent
```
"merge #<N>"
```
, once no reviewer is left unresolved. That is this phase's half of the gate; Step 6 supplies the other half by waiting on CI. A bot that timed out counts as unresolved: report it and leave the pull request open rather than merging through it. A human thread held for a person does not block the merge — it can never be resolved, so waiting on it has no achievable meaning.
PR only — print the open-thread state and stop.

pr-review

is not installed, list the open threads with their authors and claims and stop there. Do not hand-roll replies: this skill carries no verification discipline for someone else's claim, and an unverified rejection posted in public cannot be taken back.

附加

references/report-format.md

指定的审核反馈块——包括修复的变更内容，因为合并的代码是阶段6总结未描述的——然后结束最终操作：

PR + 合并 — 当所有审核人员的问题都解决后，调用
```
issue-flow
```
，意图为
```
"merge #<N>"
```
。这是此阶段的部分环节；步骤6通过等待CI完成提供另一部分环节。超时的机器人视为未解决：报告它并保持拉取请求打开，不要绕过它合并。人工线程由人员处理，不阻止合并——它永远无法解决，等待它没有意义。
仅创建PR — 打印开放线程状态并停止。

如果未安装

pr-review

，列出开放线程及其作者和声明并停止。请勿手动编写回复：本技能不具备验证他人声明的规则，公开发布未经验证的拒绝无法撤回。

Error Handling

错误处理

Situation	Action
`gh` not authenticated	`issue-flow` or `issue-analyze` reports it — stop, relay it
Not in a git repo	Stop: `Not inside a git repository.`
Issue closed	Stop after Phase 1, print `issue-analyze` status
Open blocker	Stop after Phase 1 unless user explicitly says to proceed
Working tree dirty before Phase 2	Stop: `Uncommitted changes on base branch — resolve first.`
Verification keeps failing	Stop after 2 fix attempts in Phase 3/4, hand back to user
`changes-review` unavailable	Note it in the summary, skip Phase 4.6, continue to Phase 5
`tests-audit` unavailable	Run its gate inline per `references/tests-audit-pass.md`
No bot pending and none has reported	`PR only` : say `No automated reviewers` , stop. `PR + merge` : unknown — poll while CI runs
A pending bot never reports in budget	Say which timed out; leave the PR open, do not merge through it
A bot reported having never been requested	The detection table is disproved — say so and stop trusting it
`pr-review` unavailable	List the open threads and stop; never hand-roll a reply
Nothing in the project can be run	Report the observation `unverified` with the absence named
Advisor fixes break verification twice	Revert those fixes, list them as Notes, continue to Phase 5
Simplification breaks a check	Revert it — behavior-preserving means the check should not move
User picks `Stop` on any AskUserQuestion	Exit cleanly, leave local state as-is
Host has no structured-choice tool	Numbered list in chat per Asking the User, wait for a number
Host cannot chain skills	Use each call site's documented inline fallback

情况	操作
`gh` 未认证	`issue-flow` 或 `issue-analyze` 会报告——停止并转达该信息
不在git仓库中	停止： `Not inside a git repository.`
Issue已关闭	阶段1后停止，打印 `issue-analyze` 的状态
存在未解决的障碍	阶段1后停止，除非用户明确指示继续
阶段2前工作树有未提交变更	停止： `Uncommitted changes on base branch — resolve first.`
验证持续失败	阶段3/4中两次修复尝试后停止，交还给用户
`changes-review` 不可用	在总结中说明，跳过阶段4.6，继续到阶段5
`tests-audit` 不可用	按照 `references/tests-audit-pass.md` 内联运行其检查
没有待处理机器人且无反馈	`仅创建PR` ：说明 `No automated reviewers` 并停止。 `PR + 合并` ：未知——CI运行时轮询
待处理机器人在预算内未反馈	说明哪个超时；保持PR打开，不要绕过它合并
未被指定的机器人提交了反馈	检测表格被证明错误——说明并停止信任它
`pr-review` 不可用	列出开放线程并停止；绝不要手动编写回复
项目中无内容可运行	报告 `unverified` 观测结果，并说明缺失的内容
顾问修复两次破坏验证	回滚这些修复，列为备注，继续到阶段5
简化破坏检查	回滚——不改变行为意味着检查不应失败
用户在任何AskUserQuestion中选择 `Stop`	干净退出，保留本地状态不变
宿主无结构化选择工具	按照询问用户的方式在聊天中列出编号选项，等待用户回复编号
宿主无法进行技能链调用	使用每个调用点记录的内联回退方案

Scope

范围

This skill is for issues the user already decided are simple enough to delegate end-to-end. If

issue-analyze

surfaces an epic, a multi-file architecture decision, or a contract change, trigger the Phase 2 plan approval gate rather than attempting it silently.

本技能适用于用户已判定为足够简单、可委托端到端处理的issue。如果

issue-analyze

发现史诗任务、多文件架构决策或合约变更，触发阶段2的规划批准环节，而非尝试静默处理。