cto-review

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Purpose

目的

Strategic CTO-level review of a single PR, partitioned into isolated stages so the critical judgement (the whole-diff review) runs in a clean context window. Stage 01 gathers PR metadata, the full diff, repo context, and merge state. Stage 02 reviews the WHOLE diff cohesively across all dimensions (docs gaps, external deps, downstream/template impact, correctness, security, merge strategy, action items) in isolated context. Stage 03 runs inline: posts the GH review comment, applies the verdict label, merges-or-labels honoring merge state, writes the report file, and emits the outcome marker.

This proc is PR review ONLY. There is no heartbeat mode.

针对单个PR进行CTO级别的战略评审，拆分为独立阶段，确保关键评审（全差异代码评审）在干净的上下文窗口中进行。阶段01收集PR元数据、完整差异代码、仓库上下文和合并状态。阶段02在独立上下文中从各个维度（文档缺口、外部依赖、下游/模板影响、正确性、安全性、合并策略、行动项）全面评审完整差异代码。阶段03为内联执行：发布GH评审评论、应用裁决标签、根据合并状态执行合并或添加标签、写入报告文件，并输出结果标记。

此流程仅用于PR评审，无心跳模式。

Arguments

参数

Param	Required	Default	Notes
`PR_NUMBER`	yes	—	PR number to review
`org/repo`	yes	—	Target repository, e.g. `fellowship-dev/booster-pack`

Parse positionally from

$ARGUMENTS

: first token = PR number, second token =

org/repo

. Example:

/cto-review 742 fellowship-dev/booster-pack

参数	是否必填	默认值	说明
`PR_NUMBER`	是	—	要评审的PR编号
`org/repo`	是	—	目标仓库，例如 `fellowship-dev/booster-pack`

从

$ARGUMENTS

中按位置解析：第一个标识 = PR编号，第二个标识 =

org/repo

。示例：

/cto-review 742 fellowship-dev/booster-pack

。

What it does

功能说明

3-stage ICM procedure (sequential):

Stage	Mode	Description
01-setup	subagent	Fetch repo context, PR metadata, full diff, merge state. Short-circuit if CLOSED-not-merged or if infra/backend PR lacks staging evidence. Evidence is searched in the PR body first, then in comments (newest-first). `*.d.mts` (type-declaration) files are excluded from the infra/backend necessity trigger. Docs/test/type-only PRs are waived with a recorded rationale.
02-review	subagent	ONE cohesive review of the whole diff across all dimensions → verdict + checklist + action items.
03-synthesize-act	inline	Post GH comment, apply label, merge-or-label honoring merge state, write report file, emit outcome marker.

Stage 02 is the isolated critical-judgement step — it receives only the setup handoff and its own CONTEXT.md, never orchestrator history.

3阶段ICM流程（顺序执行）：

阶段	模式	描述
01-setup	subagent	获取仓库上下文、PR元数据、完整差异代码、合并状态。如果PR已关闭未合并，或基础设施/后端PR缺少staging证据，则直接终止流程。优先在PR正文中查找证据，再按最新优先顺序在评论中查找。 `*.d.mts` （类型声明）文件不会触发基础设施/后端PR的证据校验要求。文档/测试/仅类型变更的PR会豁免校验并记录理由。
02-review	subagent	从所有维度对完整差异代码进行一次全面评审 → 生成裁决结果、检查清单和行动项。
03-synthesize-act	inline	发布GH评论、应用标签、根据合并状态执行合并或添加标签、写入报告文件、输出结果标记。

阶段02是独立的关键评审步骤——仅接收阶段01的交付内容和自身的CONTEXT.md，不会获取编排器历史记录。

Handoff locations

交付内容存储位置

All handoffs live in the repo working directory:

.procedure-output/cto-review/{stage}/handoff.md

Stage 01 writes setup. Stage 02 reads only the setup handoff. Stage 03 reads both.

所有交付内容存储在仓库工作目录中：

.procedure-output/cto-review/{stage}/handoff.md

阶段01写入初始化内容。阶段02仅读取阶段01的交付内容。阶段03读取前两个阶段的交付内容。

Execution

执行流程

Stage 01 (subagent)

阶段01（subagent）

Spawn one Task. Pass only the arguments (PR number, org/repo) and the stage CONTEXT.md path.

Task prompt template:

You are running stage 01-setup of the cto-review procedure.

Arguments:
  PR_NUMBER = {PR}
  REPO = {org/repo}

Read your stage instructions:
  skills/cto-review/stages/01-setup/CONTEXT.md

Write your output to:
  .procedure-output/cto-review/01-setup/handoff.md

Execute all steps in CONTEXT.md. Write handoff.md before exiting.

After stage 01 completes, read

.procedure-output/cto-review/01-setup/handoff.md

and check

short_circuit

If
```
short_circuit: closed-no-merge
```
→ skip stage 02, go straight to stage 03 (which posts nothing and emits the blocked/closed outcome).

short_circuit: missing-staging-evidence

→ DO NOT run stage 02 or 03. Instead, run these steps inline:

Apply

needs-work

label:

bash

gh pr edit {PR} --repo {org/repo} --add-label "needs-work"

Post rejection comment:

bash

gh pr comment {PR} --repo {org/repo} \
  --body "Missing staging evidence. Deploy to staging with \`/test-in-staging\` and include the output before requesting re-review."

Emit outcome:

[pylot] outcome="cto-review blocked: missing staging evidence on PR #{PR}" status=blocked

Then stop — no further stages.

Otherwise → continue to stage 02.

启动一个任务。仅传递参数（PR编号、org/repo）和阶段CONTEXT.md路径。

任务提示模板：

You are running stage 01-setup of the cto-review procedure.

Arguments:
  PR_NUMBER = {PR}
  REPO = {org/repo}

Read your stage instructions:
  skills/cto-review/stages/01-setup/CONTEXT.md

Write your output to:
  .procedure-output/cto-review/01-setup/handoff.md

Execute all steps in CONTEXT.md. Write handoff.md before exiting.

阶段01完成后，读取

.procedure-output/cto-review/01-setup/handoff.md

并检查

short_circuit

字段：

如果
```
short_circuit: closed-no-merge
```
→ 跳过阶段02，直接进入阶段03（不发布任何内容，输出已阻止/已关闭的结果）。

如果

short_circuit: missing-staging-evidence

→ 不要运行阶段02或03。改为内联执行以下步骤：

应用

needs-work

标签：

bash

gh pr edit {PR} --repo {org/repo} --add-label "needs-work"

发布拒绝评论：

bash

gh pr comment {PR} --repo {org/repo} \
  --body "Missing staging evidence. Deploy to staging with \`/test-in-staging\` and include the output before requesting re-review."

输出结果：

[pylot] outcome="cto-review blocked: missing staging evidence on PR #{PR}" status=blocked

然后终止流程——不再执行后续阶段。

其他情况 → 继续执行阶段02。

Stage 02 (subagent)

阶段02（subagent）

Spawn one Task. Pass only the stage 01 handoff path and the stage CONTEXT.md path. Do NOT pass orchestrator history or any prior reasoning — the review must run in clean isolated context.

Task prompt template:

You are running stage 02-review of the cto-review procedure.

Read your stage instructions:
  skills/cto-review/stages/02-review/CONTEXT.md

Your inputs:
  .procedure-output/cto-review/01-setup/handoff.md

Write your output to:
  .procedure-output/cto-review/02-review/handoff.md

Review the WHOLE diff cohesively across all dimensions. Write handoff.md before exiting.

Await stage 02 before proceeding to stage 03.

启动一个任务。仅传递阶段01的交付内容路径和阶段CONTEXT.md路径。不要传递编排器历史记录或任何先前的推理内容——评审必须在干净的独立上下文中进行。

任务提示模板：

You are running stage 02-review of the cto-review procedure.

Read your stage instructions:
  skills/cto-review/stages/02-review/CONTEXT.md

Your inputs:
  .procedure-output/cto-review/01-setup/handoff.md

Write your output to:
  .procedure-output/cto-review/02-review/handoff.md

Review the WHOLE diff cohesively across all dimensions. Write handoff.md before exiting.

等待阶段02完成后再进入阶段03。

Stage 03 (inline)

阶段03（inline）

Run stage 03 yourself (orchestrator context). Read CONTEXT.md:

skills/cto-review/stages/03-synthesize-act/CONTEXT.md

Post the comment, apply the label, merge-or-label, write the report file, and emit the

[pylot] outcome=...

marker from the orchestrator (not from a subagent).

在编排器上下文中自行运行阶段03。读取CONTEXT.md：

skills/cto-review/stages/03-synthesize-act/CONTEXT.md

发布评论、应用标签、执行合并或添加标签、写入报告文件，并从编排器（而非subagent）输出

[pylot] outcome=...

标记。

Stage handoff chain

阶段交付链

01-setup ──► 02-review ──► 03-synthesize-act (inline, reads 01 + 02)
   │               ▲
   ├── short_circuit: closed-no-merge ──────────────────────► 03 (no-op)
   └── short_circuit: missing-staging-evidence ──► inline rejection (no stages 02/03)

01-setup ──► 02-review ──► 03-synthesize-act (inline, reads 01 + 02)
   │               ▲
   ├── short_circuit: closed-no-merge ──────────────────────► 03 (no-op)
   └── short_circuit: missing-staging-evidence ──► inline rejection (no stages 02/03)

Exit paths

退出路径

Success: stage 03 emits

[pylot] outcome="cto-review PR #{N} complete — verdict={verdict}, action={merged|labeled}" status=success

Failure: failing stage emits

[pylot] outcome="cto-review failed at stage NN: {reason}" status=failed

Blocked (closed):

[pylot] outcome="cto-review skipped: PR #{N} closed without merge" status=blocked

Blocked (evidence):
```
[pylot] outcome="cto-review blocked: missing staging evidence on PR #{N}" status=blocked
```
(fires only when staging IS required AND no valid fresh evidence was found in body or comments)

成功：阶段03输出

[pylot] outcome="cto-review PR #{N} complete — verdict={verdict}, action={merged|labeled}" status=success

失败：执行失败的阶段输出

[pylot] outcome="cto-review failed at stage NN: {reason}" status=failed

已阻止（关闭）：

[pylot] outcome="cto-review skipped: PR #{N} closed without merge" status=blocked

已阻止（缺少证据）：
```
[pylot] outcome="cto-review blocked: missing staging evidence on PR #{N}" status=blocked
```
（仅当需要staging证据且在正文或评论中未找到有效最新证据时触发）

Hard Rules

硬性规则

Sequential only — one subagent at a time, never parallel Task launches.
Stage 02 is the isolated judgement step — it receives ONLY the setup handoff + its CONTEXT.md.
Never pass full orchestrator context into subagent Task prompts — inputs only.
The whole diff is reviewed in ONE cohesive stage — never split per-file or per-dimension.
Stage 03 runs inline — GH side effects and the
```
[pylot] outcome=...
```
marker MUST come from the orchestrator.
Each stage writes handoff.md before the next stage reads it.
Do not skip stages — every stage executes, except stage 02 is skipped only on the CLOSED-no-merge short-circuit.
Honor merge state — never merge a CLOSED PR; for an already-merged PR, post the review as a post-merge note and never attempt merge.
Never merge if CI is red — even on an LGTM verdict.
No Quest — reporting is the local report file only.
Staging evidence gate fires first — if
```
short_circuit: missing-staging-evidence
```
, skip everything else and post the rejection inline. This gate cannot be bypassed.
Scope by the verification manifest, don't assume (#2210) — setup extracts the LAST
```
review-state v1
```
block; the review trusts what the manifest covers, spot-checks what it doesn't, treats still-open ledger findings as verdict inputs, and stage 03 re-posts the finalized block as valid JSON. No block found → pre-#2210 fallback (assume earlier phases covered code quality).

仅允许顺序执行——同一时间仅启动一个subagent任务，绝不并行启动任务。
阶段02是独立评审步骤——仅接收初始化交付内容 + 自身的CONTEXT.md。
绝不传递完整编排器上下文到subagent任务提示中——仅传递输入内容。
完整差异代码需在一个阶段内完成全面评审——绝不按文件或维度拆分评审。
阶段03内联执行——GH侧操作和
```
[pylot] outcome=...
```
标记必须来自编排器。
每个阶段必须先写入handoff.md，再由下一个阶段读取。
不得跳过阶段——所有阶段都需执行，仅当触发closed-no-merge终止流程时跳过阶段02。
尊重合并状态——绝不合并已关闭的PR；对于已合并的PR，发布评审作为合并后备注，绝不尝试再次合并。
CI失败时绝不合并——即使评审结果为LGTM（Looks Good To Me）也不合并。
无Quest——仅生成本地报告文件作为输出。
staging证据校验优先触发——如果
```
short_circuit: missing-staging-evidence
```
，跳过所有其他步骤并内联发布拒绝信息。此校验关卡不可绕过。
按验证清单确定范围，不做假设（#2210）——初始化阶段提取最后一个
```
review-state v1
```
块；评审信任清单覆盖的内容，抽查未覆盖的部分，将仍未解决的问题作为裁决输入，阶段03重新发布最终块为合法JSON。未找到块时 → 回退到#2210之前的逻辑（假设前期环节已覆盖代码质量）。

Reference files

参考文件

```
CONTEXT.md
```
— architecture overview
```
shared/review-comment-format.md
```
— exact GH review-comment template (verbatim from the original skill)
```
shared/report-format.md
```
— local report-file template
```
stages/NN-name/CONTEXT.md
```
— per-stage inputs, task, output contract

```
CONTEXT.md
```
— 架构概述
```
shared/review-comment-format.md
```
— 精确的GH评审评论模板（与原技能完全一致）
```
shared/report-format.md
```
— 本地报告文件模板
```
stages/NN-name/CONTEXT.md
```
— 各阶段的输入、任务、输出约定