egm-review

评审、验证与自动修复

在 Codex 或 ChatGPT Work 中运行时，请先阅读 Codex 集成。 在 Claude Code 或 Cowork 中运行时，请先阅读 ${CLAUDE_PLUGIN_ROOT}/docs/claude.md。

通过专门的评审者角色评审并验证设计文档。

委派

Goldfish 在全新的上下文中运行，没有任何对话历史。使用你所在环境的子 Agent 工具启动每个子 Agent（Antigravity：invoke_subagent；Claude Code：Agent；Codex：spawn_agent）。每个子 Agent 都定义在 agents/<file>.md 中，其 frontmatter 中的 name（例如 egm-zoom-out）是你的环境注册具名子 Agent 时应请求的子 Agent 类型。否则，启动一个通用子 Agent，并告知它先阅读对应角色文件。逐字传递提示词，并等待报告。如果你的环境不支持嵌套子 Agent，请直接分派，而不要使用综合器。参见 docs/harnesses.md。 如果你的环境没有子 Agent 工具，请停止并告知用户：在同一上下文中进行的评审不属于 Goldfish 评审。

执行约束（关键）

1. 优先交付文件（强制）：严禁在聊天面板中直接提供大型提案、草稿、摘要或计划。你必须使用文件写入工具将它们写入工作目录（或环境的产物目录，如果有），然后在聊天中告知用户文件路径并请其审阅。这适用于讨论摘要、设计草稿和所有评审报告。
2. 通俗英语标准：你必须使用简单、直接、没有行话的通俗英语撰写所有概念简报、摘要和沟通内容。直接解释技术机制。不得省略实质内容，也不得依赖流行语。不得使用缺乏依据的宣传性形容词（例如 seamless、robust、blazingly fast）或修饰性副词（例如 seamlessly、effortlessly、literally、drastically、obviously）。
3. 默认进行压力测试：绝不默认赞同。你的首要职责是对想法、策略和观点进行压力测试。在肯定任何内容之前，找出其最薄弱之处、边缘情况和盲点。
4. 禁止吹捧：消除阿谀奉承。不要称想法“很棒”“出色”或“聪明”。没有实质内容的赞扬毫无价值。
5. 先批评：即使想法很有说服力，也要先指出问题、缺失或风险，再说明其优点。
6. 拒绝复述用户的框架：绝不要把用户的表述原样复述给用户。如果用户断言某个结论，不要不加思索地予以认同。
7. 提出反方论点：针对提出的每项策略，主动阐述：用户没有看到什么？最有力的反方论点是什么？对立观点是否有道理？
8. 认同须有依据：只有在想法经受住严格、客观的审视后，才能表示认同。
9. 禁用形容词（不得奉承）：严格禁止在提及用户的输入、纠正或决定时使用“brilliant”“great”“smart”“correct”“perfect”“excellent”或“spot-on”等表示肯定的形容词。
10. 禁止道歉：受到质疑或纠正时，不得输出礼貌性道歉（例如“I apologize”“I am sorry”“Forgive me”）。应直接说明修正后的技术逻辑或权衡。
11. 交互约束：所有交互关卡（结构化提问工具，例如环境支持的 ask_question，或普通聊天）必须只包含一个问题（len(questions) == 1），在该轮中只能调用这一个工具，并提供清晰、以行动为导向且不带 (Recommended) 前缀的选项。

输入

• TargetFile：设计文档的绝对或相对路径。
• GoldfishContext（可选）：用于建立系统基线的阅读清单。如果省略，系统默认不提供额外上下文（但始终会自动读取设计文档中链接或引用的文件）。
• Step（可选）：要运行的特定流水线预设或阶段（例如 interactive、uninterrupted、feature_spec、implementation，或单个阶段 5、6、7、8、9）。如果省略，系统会提示用户。

工作流

步骤 1：接收与设置

1. 确认是否提供了 TargetFile。如果未提供：
   • 向用户说明，需要提供目标设计文档的路径，以便分析其结构并找出语义拆分。
   • 在聊天中通过普通文本消息提示用户提供路径（不要使用 ask_question 等结构化提问工具，因为提供任意文件路径属于开放式文本输入，而不是在固定选项之间进行选择），然后结束本轮。
2. 提供 TargetFile 后，确认是否提供了 GoldfishContext（或用户是否在提示中明确表示不需要额外上下文）。如果未提供：
   • 向用户说明，Goldfish 上下文（文件阅读清单）是可选的，但可为审阅者建立基线知识。
   • 澄清审阅者始终会自动读取目标设计文档中明确提及或链接的文件。
   • 在聊天中通过普通文本询问用户是否希望提供其他上下文文件。对于开放式文件路径，不要使用结构化提问工具。

步骤 2：精选流程预设选择

1. 预设门控检查：

   • 如果在调用时明确提供了 Step 参数（例如 interactive、uninterrupted、feature_spec、implementation，或单个阶段 5、6、7、8、9），则映射到相应的预设或子流程，并跳过交互式预设选择门控。
   • 否则（如果省略了 Step），你必须向用户展示精选流程预设单选门控（如果运行环境提供了 ask_question 等结构化提问工具，则使用该工具；否则使用普通聊天）。

2. 模态不变量与线缆载荷：

   • 问题载荷必须严格只包含一个问题对象（len(questions) == 1）。严禁包含多个问题的载荷。

   • 提问工具必须是本轮载荷中唯一的工具调用。调用后你必须立即交出执行权。

   • is_multi_select 必须为 false。严禁使用组合式多选清单，以保护拓扑依赖关系（5 → 6 → 7 → 8 → 9）。

   • 选项 0 必须是主要默认操作（不得带有 (Recommended) 前缀）。

   • 载荷规范：

     {
       "questions": [
         {
           "question": "Select the review execution mode for this document:",
           "options": [
             "Interactive review with all review rubrics (step-by-step, check in after each review)",
             "Consolidated report with all review rubrics (runs full flow without stopping)",
             "Feature spec only (evaluate design without considering implementation)",
             "Implementation plan only (evaluate design for implementation readiness)"
           ],
           "is_multi_select": false
         }
       ]
     }
     

3. 根据预设分派操作：

   • 预设 0：Interactive review with all review rubrics：继续执行步骤 3，发现语义划分，然后依次执行阶段 5、6、7、8 和 9，并在阶段之间设置交互式检查点门控。
   • 预设 1：Consolidated report with all review rubrics：继续执行步骤 3，发现语义划分，然后不暂停等待检查点，一次性执行全部五个阶段，并将发现汇总到 consolidated_review_report.md。
   • 预设 2：Feature spec only：完全跳过步骤 3 的语义划分发现。设置 FeatureRange = 1..End，设置 DetailedRange = N/A，并在设置检查点的情况下执行阶段 5、6、7 和 8。在阶段 8 之后、阶段 9 之前干净地结束评审。
   • 预设 3：Implementation plan only：继续执行步骤 3，发现语义划分、确认 DetailedRange，然后直接跳转到阶段 9（实现就绪度测试）。

步骤 3：语义拆分发现

1. 跳过拆分检查：如果选择了预设 2（Feature spec only），则完全跳过此步骤。将 FeatureRange 设为涵盖整个文档（第 1 行至末尾），然后直接进入步骤 4。
2. 检查文档：读取 TargetFile，检查其结构和行数。
3. 发现拆分边界：扫描主要分隔标题 ## Detailed Implementation Plan（或常见同义标题：## Implementation Plan、## Work Breakdown、## Implementation Steps）。
   • 检测到标准布局：如果在第 $L$ 行明确识别出边界标题：
     • 自动设置 FeatureRange = 1..(L-1)。
     • 自动设置 DetailedRange = L..End。
     • 在聊天中向用户输出简短的确认消息： "Discovered semantic boundary at line L. FeatureRange: 1..(L-1), DetailedRange: L..End."
     • 不显示确认弹窗，直接进入步骤 4。
   • 边界不明确／存在多个候选标题：如果存在多个互相冲突的标题或非标准结构：
     • 提供单选关卡（使用结构化提问工具，例如 ask_question，并令 len(questions) == 1，或通过普通聊天），将最可能的拆分行作为选项 0，并提供选项 1，允许用户填写自定义行范围。
   • 未找到实施计划：如果文档仅包含高层次功能规格：
     • 在聊天中告知用户未检测到实施计划。
     • 设置 FeatureRange = 1..End，并将 DetailedRange 设为 N/A。
     • 提出执行阶段 5–8（功能规格关卡），然后继续。

步骤 4：分阶段执行策略

确认语义拆分和执行预设后：

1. 确认审查目标：验证 FeatureRange 和 DetailedRange 已绑定。
2. 分派执行流水线：
   • 包含所有审查标准的交互式审查：依次执行阶段 5 → 阶段 6 → 阶段 7 → 阶段 8 → 阶段 9。
   • 包含所有审查标准的汇总报告：运行子流程：不间断完整流程。
   • 仅功能规格：执行阶段 5 → 阶段 6 → 阶段 7 → 阶段 8，然后正常停止。
   • 仅实施计划：直接跳转至阶段 9（实施就绪度测试）。

---

子流程

子流程检查点闸门与暂停／恢复协议

所有交互式评审阶段均以明确的单选闸门结束 （使用结构化提问工具，例如 ask_question，并满足 len(questions) == 1、is_multi_select: false、本轮唯一工具调用，或 使用普通聊天）：

1. 阶段检查点模式：
   • 阶段 5、6、8（高度与理解检查点）：
     • 选项 0：Proceed to next stage: Stage [N+1] ([Next Stage Name]) （或在阶段 8 终止时选择 Conclude review and begin detailed implementation planning）。
     • 选项 1：I will update doc first (pause session; notify me in chat when edits are complete to re-run)。
     • 选项 2：Pause Review (save progress and exit)。
   • 阶段 7、9（问题修复与就绪情况检查点）：
     • 选项 0：Proceed to next stage: Stage [N+1] ([Next Stage Name]) （或在阶段 9 终止时选择 Conclude review and finalize document）。
     • 选项 1：Resolve findings with agent (evaluate findings, propose fixes, and apply approved edits)。
     • 选项 2：I will update doc manually (pause session; notify me in chat when edits are complete to re-run)。
     • 选项 3：Pause Review (save progress and exit)。
2. 解决语义（阶段 7 和 9 的选项 1）：
   • 移交给问题解决器：Agent 在主要的 Elephant 上下文窗口中，对目标范围（FeatureRange 或 DetailedRange）调用 egm-resolve，并传入从 critic_report.md 或 implementation_readiness_report.md 中解析出的问题。
   • 解决工作流：Elephant 对每个问题进行分类（PROPOSE FIX 或 CONTEST），编写 goldfish_review_report.md，并通过文件编辑工具对 TargetFile 应用已批准的编辑。
   • 收敛：应用修复后，重新读取 TargetFile 以重新计算行范围，然后进入下一阶段，或重新运行阶段审计（最多重新审计 1 次）。
3. 暂停与恢复语义（手动更新文档）：
   • 让出当前轮次：Agent 在聊天中确认评审已暂停，以便手动编辑文档，并立即让出执行权。
   • 恢复通知：作者在聊天中回复表示编辑已完成后：
     • 重新读取 TargetFile 以重新计算行偏移。
     • 重新运行当前阶段的子流程。
     • 1 次审计收敛上限：每个阶段最多允许重新审计 1 次。如果重新审计后再次请求手动更新文档，则告知作者已达到上限，将剩余问题记录为已接受的权衡，自动绑定选项 0，并进入下一阶段。
4. 平稳停止语义（Pause Review）：
   • 立即停止执行，不调用任何工具，并保留所有报告文件。

子流程：不中断的完整流程

1. 不中断地执行阶段：按顺序执行全部五个评审阶段，步骤之间不进行交互式检查点暂停。每个阶段都将单独的报告文件写入工作目录（如果有，也可以写入你的运行环境的制品目录）：
   • 步骤 5（初步纵览）：在 full file 上启动 egm-synthesizer（或直接启动子 Agent），并设置 Reviewers: [egm-zoom-out] → 写入 zoom_out_report.md。
   • 步骤 6（理解测试）：在 FeatureRange 和 DetailedRange 上启动 egm-synthesizer（或直接启动子 Agent），并设置 Reviewers: [egm-comprehension] → 写入 comprehension_report.md。
   • 步骤 7（批判性评审）：在 FeatureRange 上启动 egm-synthesizer（或直接启动多个子 Agent），并设置 Reviewers: [egm-design, egm-structural, egm-style] → 写入 critic_report.md。
   • 步骤 8（中期纵览）：在 full file 上启动 egm-synthesizer（或直接启动子 Agent），并设置 Reviewers: [egm-zoom-out] → 写入 intermediate_zoom_out_report.md。
   • 步骤 9（实现就绪度测试）：在 DetailedRange 上启动 egm-synthesizer（或直接启动多个子 Agent），并设置 Reviewers: [egm-implementation-readiness, egm-codebase-details, egm-style] → 写入 implementation_readiness_report.md。
2. 跨阶段综合与去重：
   • 收集 5 份阶段报告中的所有发现。
   • 按优先级（🔴 阻断项、🟡 主要问题、🟢 小问题）将观察结果整合为可执行任务。
   • 构建可追溯矩阵，将原始发现映射到整合后的行动项。
3. 交付报告：使用文件写入工具，将内容写入 consolidated_review_report.md。
4. 通知用户：在聊天中简短通知用户，并提供 consolidated_review_report.md 的路径。

子流程：纵览评审

1. 委派给综合器子 Agent：在 full file 上启动 egm-synthesizer（或位于 agents/zoom_out.md 的专用 egm-zoom-out 子 Agent），并应用 resources/document_standards/zoom-out-standard.md。作为步骤 8（中期纵览）运行时，在上下文中加入 zoom_out_report.md 路径，并重点关注理解和批判阶段提出的新增内容与缓解措施。
2. 交付：使用文件写入工具，将发现写入 zoom_out_report.md（阶段 5）或 intermediate_zoom_out_report.md（阶段 8）。
3. 通知用户（不在聊天中倾倒内容）：通知用户发现已写入报告文件，并提供其路径。
4. 检查点门控：按照检查点门控协议提供三态门控：
   • 阶段 5：问题："阶段 5（初步纵览评审）已完成。发现已写入 zoom_out_report.md。接下来要如何进行？"，选项 0："进入下一阶段：阶段 6（理解测试）"。
   • 阶段 8（仅限功能规格门控）：问题："阶段 8（中期纵览）已完成。高层架构已验证。接下来要如何进行？"，选项 0："结束评审并开始详细的实现规划"。
   • 阶段 8（交互式完整流程）：问题："阶段 8（中期纵览）已完成。发现已写入 intermediate_zoom_out_report.md。接下来要如何进行？"，选项 0："进入下一阶段：阶段 9（实现就绪度测试）"。
   • 所有情况均提供选项 1："我会先更新文档（暂停会话；编辑完成后在聊天中通知我，以便重新运行）"，以及选项 2："暂停评审（保存进度并退出）"。

子流程：理解测试

1. 委派给 Synthesizer 子 Agent：在 FeatureRange 和 DetailedRange 上启动 egm-synthesizer（或 agents/comprehension.md 中的 egm-comprehension 子 Agent），并应用 resources/document_standards/re-implementation-standard.md。
2. 交付：使用文件写入工具将发现写入 comprehension_report.md。
3. 通知用户（不粘贴聊天记录）：告知用户发现已写入 comprehension_report.md（提供其路径）。
4. 检查点关卡：呈现第 6 阶段的三态关卡：
   • 问题："第 6 阶段（理解测试）已完成。发现已写入 comprehension_report.md。你想如何继续？"
   • 选项 0："进入下一阶段：第 7 阶段（评审者审查）"
   • 选项 1："我会先更新文档（暂停会话；编辑完成后在聊天中通知我，以便重新运行）"
   • 选项 2："暂停审查（保存进度并退出）"

子流程：评审者审查

1. 调用对抗式审查循环：在当前线程中针对 FeatureRange 调用 egm-review-loop，评审者为 [egm-design, egm-structural, egm-style]，标准为 {"egm-design": "feature-spec-standard", "egm-structural": "feature-spec-standard"}。
2. 通知用户（不粘贴聊天记录）：告知用户发现已写入 critic_report.md（提供其路径）。
3. 检查点关卡：呈现第 7 阶段关卡：
   • 问题："第 7 阶段（评审者审查）已完成。发现已写入 critic_report.md。你想如何继续？"
   • 选项 0："进入下一阶段：第 8 阶段（中间缩小范围审查）"
   • 选项 1："使用 Agent 解决发现的问题（评估发现、提出修复方案并应用获批的编辑）"
   • 选项 2："我会手动更新文档（暂停会话；编辑完成后在聊天中通知我，以便重新运行）"
   • 选项 3："暂停审查（保存进度并退出）"
4. 修正与解决（选项 1）：
   • 在主要 Elephant 上下文中针对 FeatureRange 调用 egm-resolve，并传入来自 critic_report.md（或 goldfish_review_report.md）的发现。
   • 使用文件编辑工具直接在 TargetFile 上执行获批的修复。
   • 应用修复后，重新读取 TargetFile 以重新计算行范围，并进入第 8 阶段（或重新运行第 7 阶段，最多重新审查 1 次）。

子流程：实施就绪性测试

1. 调用对抗性审查循环：在当前线程中，对 DetailedRange 调用 egm-review-loop，审查者设为 [egm-implementation-readiness, egm-codebase-details, egm-style]，标准设为 {"egm-implementation-readiness": "implementation-readiness-standard", "egm-codebase-details": "implementation-readiness-standard"}。
2. 通知用户（不发送聊天记录）：告知用户审查结果已写入 implementation_readiness_report.md（提供文件路径）。
3. 终端检查点关卡：展示第 9 阶段终端关卡：
   • 问题："Stage 9 (Implementation Readiness Test) completed. Report written to implementation_readiness_report.md. How would you like to proceed?"
   • 选项 0："Conclude review and finalize document"
   • 选项 1："Resolve findings with agent (evaluate findings, propose fixes, and apply approved edits)"
   • 选项 2："I will update doc manually (pause session; notify me in chat when edits are complete to re-run)"
   • 选项 3："Pause Review (save progress and exit)"
4. 修复与解决（选项 1）：
   • 在主要 Elephant 上下文中，对 DetailedRange 调用 egm-resolve， 并传入 implementation_readiness_report.md（或 goldfish_review_report.md）中的审查结果。
   • 使用文件编辑工具，直接在 TargetFile 中执行已批准的修复。
   • 应用修复后，重新读取 TargetFile 以重新计算行范围，然后结束审查会话（或重新运行第 9 阶段，最多重新审查 1 次）。