egm-review-loop

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Goldfish Review: Loop (Orchestration Driver)

Goldfish Review：循环（编排驱动程序）

When running in Codex or ChatGPT Work, first read Codex integration. In Claude Code or Cowork, read

${CLAUDE_PLUGIN_ROOT}/docs/claude.md

first.

在 Codex 或 ChatGPT Work 中运行时，请先阅读 Codex integration。在 Claude Code 或 Cowork 中运行时，请先阅读

${CLAUDE_PLUGIN_ROOT}/docs/claude.md

。

Overview

概述

This skill acts as the central orchestration engine driving the multi-agent review loop. It coordinates two distinct agent memory models:

The Goldfish (Adversarial Auditors): Subagents spawned in isolated, fresh context windows to catch unstated assumptions without historical bias.
The Elephant (Persistent Resolver): The primary agent context holding institutional knowledge to evaluate findings and apply approved repairs.

The driver manages argument intake, resolves paths for reviewers and standards, unconditionally re-parses target line ranges before every iteration, spawns concurrent specialized Goldfish auditors based on configuration, and coordinates with the Elephant context to resolve findings.

此 skill 充当中央编排引擎，驱动多 Agent 审查循环。它协调两种不同的 Agent 记忆模型：

The Goldfish（对抗性审核者）：在隔离、全新的 context window 中启动的 subagent，用于发现未言明的假设，避免历史偏见干扰。
The Elephant（持久化解决者）：持有机构知识的主要 Agent context，用于评估审查发现并应用已批准的修复。

驱动程序负责接收参数、为审核者和标准解析路径、在每轮迭代前无条件重新解析目标行范围、根据配置并行启动专门的 Goldfish 审核者，并协调 Elephant context 解决发现的问题。

Delegation

委派

A Goldfish runs in a fresh context with no conversation history. Spawn each subagent with your harness's subagent tool (Antigravity:

invoke_subagent

; Claude Code:

Agent

; Codex:

spawn_agent

). Each subagent is defined in

agents/<file>.md

, and its frontmatter

name

(for example

egm-zoom-out

) is the subagent type to request where your harness registers named subagents. Otherwise spawn a general-purpose subagent and tell it to read that persona file first. Pass the prompt verbatim and wait for the report. If your harness cannot nest subagents, use direct dispatch instead of the synthesizer. See

docs/harnesses.md

. If your harness has no subagent tool, stop and tell the user: a review in the same context is not a Goldfish review.

Goldfish 在没有对话历史记录的新鲜 context 中运行。请使用 harness 的 subagent 工具启动每个 subagent（Antigravity：

invoke_subagent

；Claude Code：

Agent

；Codex：

spawn_agent

）。每个 subagent 都定义在

agents/<file>.md

中，其 frontmatter 中的

name

（例如

egm-zoom-out

）是在 harness 注册了命名 subagent 的环境中请求的 subagent 类型。否则，请启动通用 subagent，并要求其先读取对应的 persona 文件。逐字传递 prompt，然后等待报告。如果 harness 无法嵌套 subagent，请改用直接分发（direct dispatch），而不是 synthesizer。参见

docs/harnesses.md

。如果 harness 没有 subagent 工具，请停止并告知用户：同一 context 中进行的审查不属于 Goldfish review。

Inputs

输入

The caller or user provides exactly these parameters:

TargetFile
: Absolute or relative path to target document.
SemanticTarget
: Descriptive targeting string (e.g., "Target the H4 block with SS-ID 'S1.12'"), or
```
full file
```
.
Reviewers
: List of reviewer names (shortnames or paths).
Standards
: Mapping of reviewer names to standard names (shortnames or paths).
GoldfishContext
: A reading list (source files, directories, or documentation URLs) fed to reviewers to establish their baseline.

调用方或用户提供以下参数，且只能提供这些参数：

TargetFile
：目标文档的绝对路径或相对路径。
SemanticTarget
：描述性目标定位字符串（例如，“定位包含 SS-ID 'S1.12' 的 H4 区块”），或者
```
full file
```
。
Reviewers
：审核者名称列表（简称或路径）。
Standards
：审核者名称到标准名称的映射（简称或路径）。
GoldfishContext
：提供给审核者的阅读列表（源文件、目录或文档 URL），用于建立其基准认知。

Path & Standard Resolution Logic

路径与标准解析逻辑

When resolving names in

Reviewers

and

Standards

Reviewer Shortnames: Map reviewer shortname (e.g.,
```
design_critic
```
,
```
structural
```
,
```
style
```
,
```
implementation_readiness
```
,
```
codebase_details
```
,
```
comprehension
```
,
```
zoom_out
```
) to
```
agents/{name}.md
```
. The persona file defines the reviewer's core mandates, audit vectors, and output format.

Standard Shortnames: Map standard shortname (e.g.,

feature-spec-standard

implementation-readiness-standard

zoom-out-standard

heilmeier-standard

re-implementation-standard

) to

resources/document_standards/{name}.md

Custom Paths: If the name contains a slash (
```
/
```
), treat it as an absolute or workspace-relative path and read it directly.

解析

Reviewers

和

Standards

中的名称时：

审核者简称：将审核者简称（例如
```
design_critic
```
、
```
structural
```
、
```
style
```
、
```
implementation_readiness
```
、
```
codebase_details
```
、
```
comprehension
```
、
```
zoom_out
```
）映射到
```
agents/{name}.md
```
。persona 文件定义审核者的核心职责、审核维度和输出格式。

标准简称：将标准简称（例如

feature-spec-standard

、

implementation-readiness-standard

、

zoom-out-standard

、

heilmeier-standard

、

re-implementation-standard

）映射到

resources/document_standards/{name}.md

。

自定义路径：如果名称包含斜杠（
```
/
```
），则将其视为绝对路径或 workspace 相对路径，并直接读取。

Execution Workflow

执行工作流

Step 1: Intake & Configuration UX

第 1 步：参数接收与配置体验

Evaluate the provided inputs (

TargetFile

SemanticTarget

Reviewers

Standards

GoldfishContext

Identify Missing Inputs: Determine which of the required parameters are missing.
Interactive Onboarding:
- If all inputs are present, proceed to Step 2.
- If some or all inputs are missing, interactively prompt the user only for the missing inputs, one at a time via chat messages.

Reviewer Recommendations:

Feature Specs: Recommend

design_critic

(mapped to

resources/document_standards/feature-spec-standard.md

) and

structural

(mapped to

resources/document_standards/feature-spec-standard.md

Implementation Plans: Recommend

implementation_readiness

(mapped to

resources/document_standards/implementation-readiness-standard.md

) and

codebase_details

Confirm Configuration: Display the consolidated plan (Target, Reviewers, and mapped Standards) and ask the user to confirm before proceeding.

评估提供的输入（

TargetFile

、

SemanticTarget

、

Reviewers

、

Standards

、

GoldfishContext

）。

识别缺失输入：确定缺少哪些必填参数。
交互式引导：
- 如果所有输入均已提供，则进入第 2 步。
- 如果部分或全部输入缺失，则通过聊天消息逐项询问用户，仅询问缺失的输入。

审核者建议：

功能规格：建议使用

design_critic

（映射到

resources/document_standards/feature-spec-standard.md

）和

structural

（映射到

resources/document_standards/feature-spec-standard.md

）。

实施计划：建议使用

implementation_readiness

（映射到

resources/document_standards/implementation-readiness-standard.md

）和

codebase_details

。

确认配置：显示整合后的计划（Target、Reviewers 及映射后的 Standards），并在继续执行前请求用户确认。

Step 2: The Sharpening Loop (Iterative Cycle)

第 2 步：锐化循环（迭代周期）

Execute the following sequence in a continuous loop:

在连续循环中执行以下序列：

2.1 Unconditional Target Resolution

2.1 无条件目标解析

Before every iteration, unconditionally re-scan

TargetFile

by reading it and using the stable

SemanticTarget

string (e.g., locating the target header) to dynamically determine the updated absolute start and end line numbers. This ensures absolute accuracy even if the file was edited in prior rounds. (If

full file

mode is specified, confirm full-file line bounds).

每轮迭代前，都必须通过读取

TargetFile

并使用稳定的

SemanticTarget

字符串（例如，定位目标标题）来重新扫描文件，从而动态确定更新后的绝对起始行号和结束行号。即使文件在前几轮中已被编辑，也能确保定位绝对准确。（如果指定了

full file

模式，则确认全文的行范围边界。）

2.2 Review Swarm Execution

2.2 审核群执行

Launch Subagent Swarm: Spawn subagents to execute the review:
- Hierarchical Dispatch (Synthesizer): Spawn the intermediate synthesizer subagent (
```
agents/synthesizer.md
```
  /
```
egm-synthesizer
```
  ). The synthesizer spawns the Goldfish review swarm in parallel, deduplicates findings, writes the report artifact, and returns a single summary message to avoid context pollution in the root conversation. Pass it the Failed Reviewers rule below. Its summary must give a status,
```
completed
```
  or
```
not run
```
  , for each requested reviewer.
- Direct Dispatch (Flat Swarm): Alternatively, spawn each requested reviewer subagent in
```
Reviewers
```
  directly. Instruct each subagent to first read its persona definition in
```
agents/{name}.md
```
  , then audit
```
TargetFile
```
  at the resolved line range against its designated standard in
```
resources/document_standards/
```
  , supplying
```
GoldfishContext
```
  .
- Each reviewer produces findings with severity (🔴 Blocker, 🟡 Major, 🟢 Nit), line numbers, discrepancy descriptions, and rationales.
Consolidate Findings: Collect all findings across reviewers into a single flat
```
FindingsList
```
. Give each finding a stable id (
```
<reviewer>-<round>-<n>
```
) and record its reviewer, severity, and affected scope.
Failed Reviewers: A reviewer that times out, fails, or returns no report did not review. Retry it once. If it fails again, record it as not run in the report. Never count it as a reviewer with zero findings. If the synthesizer summary has no status for a requested reviewer, record that reviewer as not run.

启动 Subagent 群：
- 分层分发（Synthesizer）：启动中间 synthesizer subagent（
```
agents/synthesizer.md
```
  /
```
egm-synthesizer
```
  ）。Synthesizer 并行启动 Goldfish 审核群，对发现的问题去重，编写报告 artifact，并返回一条摘要消息，以避免污染根对话的 context。将下文的 Failed Reviewers 规则传递给该 subagent。其摘要必须针对每个请求的审核者给出一个状态：
```
completed
```
  或
```
not run
```
  。
- 直接分发（Flat Swarm）：也可以直接启动
```
Reviewers
```
  中的每个审核者 subagent。
- 要求每个 subagent 先读取
```
agents/{name}.md
```
  中对应的 persona 定义，然后根据
```
GoldfishContext
```
  ，在解析出的行范围内对照
```
resources/document_standards/
```
  中指定的标准审核
```
TargetFile
```
  。
- 每个审核者产生的发现应包含严重程度（🔴 Blocker、🟡 Major、🟢 Nit）、行号、差异描述和理由。
整合发现：将所有审核者的发现汇总到一个扁平的
```
FindingsList
```
中。为每项发现分配一个稳定 id（
```
<reviewer>-<round>-<n>
```
），并记录其审核者、严重程度和受影响范围。
审核失败者：审核者如果超时、失败或未返回报告，则视为没有完成审核。重试一次。如果再次失败，则在报告中记录为 not run。绝不能将其计为发现数量为零的审核者。如果 synthesizer 摘要中没有某个已请求审核者的状态，也将该审核者记录为 not run。

2.3 Aggregated Resolution Hand-off

2.3 聚合解决方案移交

Pass
```
TargetFile
```
, the active line range, and the aggregated
```
FindingsList
```
to the egm-resolve
workflow.
Execute the resolution workflow in the primary Elephant context:
- Categorize findings into
```
CONTEST
```
  vs.
```
PROPOSE FIX
```
  .
- Save
```
goldfish_review_report.md
```
  with your file-writing tool.
- Present the interactive decision gate (Auto accept, Continue, Interactive breakdown).
- Apply approved text repairs to
```
TargetFile
```
  using your file-editing tool.

将
```
TargetFile
```
、当前行范围和聚合后的
```
FindingsList
```
传递给 egm-resolve
工作流。
在主要的 Elephant context 中执行解决方案工作流：
- 将发现分类为
```
CONTEST
```
  或
```
PROPOSE FIX
```
  。
- 使用文件写入工具保存
```
goldfish_review_report.md
```
  。
- 展示交互式决策门（Auto accept、Continue、Interactive breakdown）。
- 使用文件编辑工具将已批准的文本修复应用到
```
TargetFile
```
  。

2.4 Iteration Check & Turn Boundary

2.4 迭代检查与轮次边界

Fresh reviewers sample differently each round, so a round with zero findings is rare even when the document improves. Use these rules instead:

Settled findings: A finding is settled when it is contested or recorded without a fix (accepted risk). Keep the settled list across rounds. If a new reviewer raises a settled finding again (same affected scope, same issue), do not re-open it.
Fixed findings: An applied fix does not settle a finding. If a later reviewer raises the same issue at the same scope, the fix failed or a later edit reintroduced the issue. Re-open the finding.
Clean round: A round is clean when no reviewer raises a Blocker or Major finding that is not settled. Nits do not block. A reviewer recorded as not run makes the round not clean. Decide this from the review results, before you apply the fixes of that round.
Converged: Two consecutive clean rounds. One clean round is not enough, because the next fresh reviewer can find a different gap in the same text.
Cap: 5 rounds.
Churn: A new finding is at the scope of an applied fix, and reverting that fix would resolve it.

On converged, go to Step 3. On cap or churn, write a short list of the open findings by severity, then ask the user one question: accept and proceed, continue past the cap, or return the document to drafting.

Crucial Turn-Taking Requirement: After the resolution phase finishes for a given round, the loop driver MUST respect the turn-taking checkpoint in
egm-resolve
. The driver must remain idle across human turns, only looping back to Step 2.1 when the user explicitly confirms they wish to run another round of review.

全新的审核者每轮采用不同的抽样方式，因此，即使文档已有改善，出现零发现的轮次也很少见。请使用以下规则：

已定案发现（Settled findings）：当一项发现被提出异议，或在未修复的情况下被记录（接受风险）时，即视为已定案。在各轮之间保留已定案发现列表。如果新的审核者再次提出已定案的发现（受影响范围相同且问题相同），则不要重新开启该发现。
已修复发现（Fixed findings）：应用修复并不会使发现进入已定案状态。如果后续审核者在相同范围内再次提出同一问题，则说明修复失败，或后续编辑重新引入了该问题。重新开启该发现。
干净轮次（Clean round）：当没有任何审核者提出尚未定案的 Blocker 或 Major 发现时，该轮即为干净轮次。Nit 不构成阻塞。存在被记录为 not run 的审核者时，该轮不属于干净轮次。应在应用该轮修复之前，根据审核结果作出判断。
收敛（Converged）：连续两个干净轮次。一次干净轮次并不充分，因为下一轮全新的审核者可能会在同一文本中发现不同的缺口。
上限（Cap）：5 轮。
扰动（Churn）：新发现位于已应用修复的影响范围内，并且撤销该修复即可解决新发现。

收敛后进入第 3 步。达到上限或出现扰动时，按严重程度列出一份简短的未解决发现列表，然后向用户提出一个问题：接受并继续、超过上限继续执行，或将文档返回起草阶段。

关键轮次交接要求：给定轮次的解决方案阶段结束后，循环驱动程序必须遵守
egm-resolve
中的轮次交接检查点。驱动程序在人类交互轮次之间必须保持空闲，只有当用户明确确认希望再运行一轮审查时，才能返回第 2.1 步。

Step 3: Output Boundary & Final Checkpoint

第 3 步：输出边界与最终检查点

Upon completion (converged, cap or churn accepted by the user, or manual halt):

Programmatic Callers: If running as a subflow of
```
egm-review
```
, exit cleanly to hand execution back to the parent workflow.
Manual Invocations: Output a summary of completion in chat: "The review loop has completed after [N] rounds ([converged | accepted at cap | halted]). Open findings are in the report. Would you like to proceed to the next stage, or do you have any final questions?"

完成后（收敛、用户接受达到上限或扰动，或手动停止）：

程序化调用方：如果作为
```
egm-review
```
的子流程运行，请干净退出，将执行权交回父工作流。
手动调用：在聊天中输出完成摘要：“审查循环已在 [N] 轮后完成（[converged | accepted at cap | halted]）。未解决的发现已写入报告。您希望继续进入下一阶段，还是有其他最终问题？”