ce-doc-review

文档审查

通过多角色分析审查需求或计划文档。调度使用技能本地审查提示资产初始化的通用子代理，自动应用 safe_auto 修复，并通过四选项交互（逐条发现走查、最佳判断自动解决、追加到开放问题、仅报告）将剩余发现路由给用户决策。

设置

在本次调用开始时运行一次，在任何子代理调度之前，并遵循其打印的指令——除非与技能自身关于向用户提问的规则冲突，无论这些规则是限定于非交互模式还是适用于所有模式，此时本技能的规则优先，且不提出阻塞性问题。在同一调用中不要重新运行；后续调用本技能或其他技能会运行各自的设置。如果没有可用的 Node 运行时，技能照常继续。

SKILL_DIR="<包含你刚读取的 SKILL.md 的目录的绝对路径>";
NODE="$(for c in node nodejs; do command -v "$c" >/dev/null 2>&1 && "$c" -e '' >/dev/null 2>&1 && { echo "$c"; break; }; done)";
if [ -n "$NODE" ]; then
"$NODE" "$SKILL_DIR/scripts/context.mjs" || echo "context 脚本失败；继续使用技能的正常行为";
else
echo "没有 Node 运行时；继续使用技能的正常行为";
fi

交互模式规则

• 在任何问题触发前预加载平台提问工具。 在 Claude Code 中，AskUserQuestion 是一个延迟工具——其模式在会话开始时不可用。在交互模式工作开始时（在路由问题、逐条发现走查问题、批量预览继续/取消以及阶段 5 终端问题之前），调用 ToolSearch，查询 select:AskUserQuestion 以加载模式。在交互流程顶部急切地加载一次——不要等待第一个问题点。在 Codex、Gemini 和 Pi 上，此预加载不是必需的。
• 编号列表回退仅适用于工具确实缺乏阻塞性提问工具的情况——ToolSearch 返回无匹配、工具调用明确失败，或运行时模式不暴露它（例如，Codex 编辑模式中 request_user_input 不可用）。待处理的模式加载不是回退触发条件；根据预加载规则先调用 ToolSearch。在真正的回退情况下，将选项呈现为编号列表并等待用户回复——切勿静默跳过问题。因为工具感觉不方便、因为模型处于报告格式化模式、或因为指令埋在长技能中而将问题渲染为叙述文本是错误。需要用户决策的问题必须触发工具或大声回退。

阶段 0：检测模式

检查调用参数中是否有 mode:headless。参数可能包含文档路径、mode:headless 或两者。以 mode: 开头的标记是标志，不是文件路径——将它们从参数中剥离，并将剩余标记（如果有）用作阶段 1 的文档路径。

如果存在 mode:headless，则为工作流的其余部分设置无头模式。

无头模式改变交互模型，不改变分类边界。对每个发现属于哪个层级应用相同的判断。只有非 safe_auto 发现的交付方式改变：

• safe_auto 修复静默应用（与交互模式相同）
• gated_auto、manual 和 FYI 发现作为结构化文本返回给调用者处理——没有阻塞性提问提示，没有交互式路由
• 阶段 5 立即返回“审查完成”（没有路由问题，没有终端问题）

调用者接收具有原始分类的发现，并决定如何处理它们。

无头参数契约： 要求 mode:headless <document-path>，例如 mode:headless <path-to-doc>.md。

如果不存在 mode:headless，则运行默认交互模式，具有 references/walkthrough.md 和 references/bulk-preview.md 中记录的路由问题、走查和批量预览行为。

工件根目录

此技能审查传递给它的路径处的文档，在交互模式且未提供路径时，发现 <root>/plans/ 下最近的计划。仅在无路径发现分支中解析 <root>（根据下面的块）——这是它组合 <root>/ 路径的唯一位置。对显式命名文档的审查直接读取该路径，从不解析 <root>；不要在每次运行开始时运行根解析，因为有效的无头或绝对路径审查（例如 /tmp/plan.md，可能在任何 git 仓库之外）不得依赖它不需要的仓库根或 CE 配置。

<!-- ce-docs-root:start -->
在组合任何工件路径之前解析 CE 工件根 <root>。

• 读取 <repo-root>/.compound-engineering/config.local.yaml 中的 docs_root，然后读取 config.yaml；第一个非空值获胜（<repo-root> = git rev-parse --show-toplevel）。未设置 -> <root> 是 docs，与之前完全相同。
• 验证设置的值：仓库相对目录，其真实、符号链接解析后的路径保持在仓库内，既不是仓库根也不是 .git/ 下。否则停止并报错，命名 docs_root 和值——绝不回退到 docs。
• 使用 <root> 作为唯一工件位置：如果不存在则创建，使用本技能自己的子目录将每个路径组合为 <root>/<subdir>，并且绝不也读取 docs。
  <!-- ce-docs-root:end -->

阶段 1：获取并分析文档

如果提供了文档路径： 读取它，然后继续。如果读取失败或文件不在磁盘上，则应用下面的缺失文档门，而不是继续。

如果未指定文档（交互模式）： 询问要审查哪个文档，或使用文件搜索/glob 工具（例如 Claude Code 中的 Glob）在 <root>/plans/ 下找到最近的。

如果未指定文档（无头模式）： 输出“审查失败：无头模式需要文档路径。预期参数：mode:headless <path>”并停止，不调度审查者。

缺失文档门——在任何调度前验证。 角色审查者从文件系统读取文档，并且几个在没有 Bash 的情况下运行，因此它们无法读取 git 引用——仅存在于未检出分支上的路径会浪费整个角色团队发现他们无法继续（问题 #925）。在阶段 2 之前，确认每个解析的文档路径在磁盘上可读（上面的读取已成功）。位置无关紧要：检出之外的绝对路径（例如 /tmp/plan.md）或其他检出中的文档可以正常审查。如果任何路径不可读，不要调度任何角色：

• 交互模式： 停止并命名缺失路径：“文档在磁盘上未找到：<paths>。检出包含它们的分支，使用工作树，或在重试审查前提供更正的可读路径。”
• 无头模式： 输出“审查失败：文档在磁盘上未找到：<paths>。预期输入：磁盘上可读文件的路径；检出包含它们的分支或提供更正路径。”并返回，不调度审查者。

分类文档类型

通过读取文档的内容形状和元数据分类文档，而不是其文件路径。在统一计划契约下，仅需求计划和实现就绪计划都位于 <root>/plans/ 中，因此位置不再指示类型——需求样式文档分类为 requirements，计划形状文档分类为 plan，无论它们位于何处。下面的审查者根据此分类以不同方式操作，因此将计划形状文档误分类为需求文档（或反之）会产生嘈杂或审查不足的发现。

首先检查统一工件契约：

• artifact_contract: ce-unified-plan/v1 加上 artifact_readiness: requirements-only -> 分类为 unified-requirements。仅审查产品契约；缺少规划契约、实施单元、验证契约或完成定义是预期的，不得标记。
• artifact_contract: ce-unified-plan/v1 加上 artifact_readiness: implementation-ready -> 分类为 unified-plan。使用不同视角审查产品契约和规划契约，然后审查实施单元/验证/完成定义的执行完整性。
• HTML 统一工件（.html）以仅报告模式读取/审查。不要将 markdown 变异路径应用于 HTML。如果调用者请求变异/自动修复行为，跳过并显示现有的仅 markdown 消息或返回仅报告发现。
• 无效的进度类就绪值（active、in_progress、completed、done）是文档契约发现，不是要遵循的执行状态。

使用这些信号来决定：

requirements 信号（构建什么文档）：

• 像 actors:、flows:、acceptance_examples: 或 status: 这样的前置字段，带有头脑风暴形状的值
• 像 Acceptance Examples、Actors、Key Flows、User Flows、Outstanding Questions、Resolve Before Planning 这样的章节标题
• 形式为 R1、R2、A1、F1、AE1 的编号标识符——需求、参与者、流程和验收示例 ID
• 专注于用户/业务问题、行为、范围边界、成功标准的散文框架
• 没有实施单元、没有每单元文件列表、没有附加到单元的测试场景

plan 信号（如何构建文档）：

• 像 type: feat|fix|refactor、origin: docs/brainstorms/... 或 product_contract_source: ce-brainstorm|ce-plan-bootstrap|legacy-requirements 这样的前置字段
• 像 Implementation Units、Output Structure、Key Technical Decisions、Risks & Dependencies、System-Wide Impact 这样的章节标题
• 形式为 U1、U2 的编号标识符——实施单元 ID
• 名为 Goal、Files、Approach、Test scenarios、Verification 的每单元字段
• 要创建/修改/测试的仓库相对文件路径
• 专注于技术决策、排序和实施者面向细节的散文框架

决胜规则。 当内容信号混合或稀疏时，将主导内容形状视为权威；如果形状真正模糊，默认 requirements（更保守的分类——它激活更少的计划特定可行性检查）。在统一计划契约下，路径位置不消除类型歧义，其中仅需求和实现就绪计划共享 <root>/plans/；遗留 origin: docs/brainstorms/... 字段（如果存在）仍根据上面的前置字段列表读取为 plan 信号。

将分类结果通过子代理模板中的 {document_type} 槽传递给每个角色。角色读取此并相应调整其分析。

选择条件角色

分析文档内容以确定激活哪些条件角色。检查这些信号：

product-lens —— 当文档对构建什么和为什么做出可挑战的声明，或提议的工作带有超出直接问题的战略权重时激活。系统的用户可能是最终用户、开发人员、操作员、维护者或任何其他受众——标准是领域无关的。检查任一腿：

腿 1——前提声明： 文档对构建什么或为什么持有立场，知识渊博的利益相关者可以合理挑战——不仅仅是描述任务或重述已知需求：

• 问题框架，其中所述需求不显而易见或可辩论，不是从现有上下文自明的
• 解决方案选择，其中替代方案可能合理存在（隐含或显式）
• 明确排序构建什么与推迟什么的优先级决策
• 预测特定用户结果的目标声明，不仅仅是重述约束或描述交付物

腿 2——战略权重： 提议的工作可能影响系统轨迹、用户感知或竞争定位，即使前提是合理的：

• 塑造系统感知方式或系统以什么闻名的更改
• 影响采用、入门或认知负荷的复杂性或简单性赌注
• 打开或关闭未来方向的工作（路径依赖、架构承诺）
• 机会成本影响——构建这个意味着不构建其他东西

design-lens —— 当文档包含以下内容时激活：

• UI/UX 引用、前端组件或视觉设计语言
• 用户流程、线框、屏幕/页面/视图提及
• 交互描述（表单、按钮、导航、模态框）
• 响应式行为或可访问性的引用

security-lens —— 当文档包含以下内容时激活：

• 认证/授权提及、登录流程、会话管理
• 暴露给外部客户端的 API 端点
• 数据处理、PII、支付、令牌、凭据、加密
• 具有信任边界影响的第三方集成

scope-guardian —— 当文档包含以下内容时激活：

• 多个优先级层（P0/P1/P2、必须有/应该有/最好有）
• 大量需求计数（>8 个不同需求或实施单元）
• 延伸目标、最好有或“未来工作”部分
• 似乎与所述目标不一致的范围边界语言
• 与需求不明确连接的目标

adversarial —— 当文档包含高价值挑战表面时激活，不仅仅是结构复杂性。具有所述理由的常规计划本身不是对抗信号——当唯一信号是“此计划结构良好”时，前提/假设工作会重新争论已解决的问题。当以下任何一项成立时激活：

• 文档是需求文档，具有 2+ 个可挑战声明（问题框架、解决方案选择、优先级、预测结果）——前提审查是头脑风暴阶段的核心
• 文档涉及高风险领域——认证、支付、计费、数据迁移、隐私/合规、外部集成、密码学——无论文档类型或大小
• 文档提出新的抽象、框架或重要架构模式——无论文档类型
• 文档是没有经过验证的上游产品契约信号的计划（没有遗留 origin: 需求文档，也没有 product_contract_source: ce-brainstorm 或 legacy-requirements）——前提未在上游验证
• 文档是明确扩展范围超出其来源需求文档的计划（新参与者、新流程、延迟然后恢复的功能）
• 文档包含显式替代方案部分或未解决的权衡——对抗有助于压力测试所选方向

不要对从经过验证的上游产品契约派生的、保持在范围内且不引入高风险领域或新抽象的常规计划文档激活对抗。经过验证的上游来源包括遗留 origin: docs/brainstorms/...、product_contract_source: ce-brainstorm 和 product_contract_source: legacy-requirements。直接 product_contract_source: ce-plan-bootstrap 计划是绿地，本身不抑制前提级技术。计划的结构决策（更多单元、更多理由）本身不是对抗信号——这些是计划在做其工作。

阶段 2：宣布并调度角色

宣布审查团队

告诉用户哪些角色将审查以及为什么。对于条件角色，包括理由：

正在审查：
- coherence-reviewer（始终开启）
- feasibility-reviewer（始终开启）
- scope-guardian-reviewer —— 计划有 12 个需求，跨 3 个优先级
- security-lens-reviewer —— 计划添加了带认证流程的 API 端点

构建代理列表

始终包括：

• coherence-reviewer
• feasibility-reviewer

添加激活的条件角色：

• product-lens-reviewer
• design-lens-reviewer
• security-lens-reviewer
• scope-guardian-reviewer
• adversarial-document-reviewer

调度

使用平台的子代理原语（例如 Claude Code 中的 Agent、Codex 中的 spawn_agent）以有界并行调度通用子代理（如果可用）；否则内联或串行运行工作。省略 mode 参数，以便应用用户配置的权限设置。尊重当前工具的活动子代理限制：排队选定的审查者，仅调度工具接受的那么多，并在审查者完成时填充释放的槽。将活动代理/线程/并发限制生成错误视为背压，而不是审查者失败：保持审查者排队并在槽释放后重试。仅在成功调度超时/失败或调度因非容量原因失败时记录审查者失败。

对于每个选定的审查者，读取匹配的技能本地提示资产 references/personas/<reviewer-name>.md，并将其完整内容作为 {persona_file} 传递。不要按类型/名称调度独立代理，也不要依赖平台级自定义代理注册。

模型分层在这里，不在提示资产中。 本地提示文件没有前置字段，也不携带模型元数据。当平台暴露已知模型覆盖时应用这些调度时偏好；否则省略覆盖并继承父模型，而不是猜测平台特定模型名称：

• coherence-reviewer：最便宜的能提取/推理层。
• design-lens-reviewer、scope-guardian-reviewer：平台中档模型。
• security-lens-reviewer、feasibility-reviewer、product-lens-reviewer、adversarial-document-reviewer：继承父模型，除非工具具有既定的高能力审查层。

每个子代理接收从下面包含的子代理模板构建的提示，并填充这些变量：

变量	值
{persona_file}	从 references/personas/ 选择的本地提示资产的完整内容
{schema}	下面包含的发现模式的内容
{document_type}	阶段 1 分类中的“requirements”、“plan”、“unified-requirements”或“unified-plan”
{document_path}	文档的路径
{origin_path}	阶段 1 期间提取一次的上游产品契约来源：当存在时优先使用文档的 origin: 前置字段；否则使用 product_contract_source:<value>（如果存在）；否则使用 none。在来源/来源上适应的角色（product-lens、adversarial、scope-guardian）读取此槽以门控技术抑制——它们自己不重新解析前置字段。
{settled_ktds}	阶段 1 期间提取一次的会话已解决决策：任何带有 session-settled: 注释的关键技术决策或产品契约关键决策条目，列为决策名称、类别（user-directed / user-approved）和拒绝的替代方案；或当文档没有此类条目时使用字面 none。角色读取此槽——它们不为此重新解析文档。
{document_content}	审查者特定部分切片。对于统一工件，传递元数据、目标胶囊和仅相关切片：product-lens/adversarial/scope 审查者获取产品契约；feasibility/coherence 审查者还获取规划契约和活动实施单元/验证/完成定义（当 artifact_readiness: implementation-ready 时）。对于遗留文档，传递完整文档。
{decision_primer}	当前会话中累积的先前轮次决策，或第 1 轮的空 <prior-decisions> 块。请参阅下面的“决策启动器”。

对于遗留需求/计划文档，将完整文档传递给每个子代理——不要分割成部分。对于统一工件，默认情况下不要将完整工件传递给每个审查者：统一计划可能很大，因此部分切片（根据上面的 {document_content} 槽）是默认。仅当审查者需要初始切片无法评估的跨部分可追溯性时，才升级到更广泛的切片。

决策启动器

在第 1 轮（没有先前决策），将 {decision_primer} 设置为：

<prior-decisions>
第 1 轮——没有先前决策。
</prior-decisions>

在第 2 轮及以后（在当前交互会话中一轮或多轮之后），累积先前轮次决策并将它们渲染为：

<prior-decisions>
第 1 轮——已应用（N 条目）：
- {section}: "{title}" ({reviewer}, {confidence})
  证据："{evidence_snippet}"

第 1 轮——已拒绝（M 条目）：
- {section}: "{title}" — 跳过因为 {reason}
  证据："{evidence_snippet}"
- {section}: "{title}" — 推迟到开放问题因为 {reason 或 "未提供原因"}
  证据："{evidence_snippet}"
- {section}: "{title}" — 已确认未应用因为 {reason 或 "无 suggested_fix — 用户确认"}
  证据："{evidence_snippet}"
- {section}: "{title}" — 撤回因为 {triggering decision}
  证据："{evidence_snippet}"

第 2 轮——已应用（N 条目）：
...
</prior-decisions>

每个条目携带 Evidence: 行，因为综合 R29（拒绝发现抑制）和 R30（修复落地验证）都使用证据子串重叠检查作为其匹配谓词的一部分——没有启动器中的证据片段，编排器无法计算 >50% 重叠测试，必须回退到仅指纹匹配，这要么重新浮出被拒绝的发现，要么过于激进地抑制。{evidence_snippet} 是发现中的第一个证据引用，截断到前约 120 个字符（在边界保留完整单词）并转义内部引号。如果发现具有多个证据条目，使用第一个；其余存在于运行工件中，不需要用于重叠检查。

在当前会话的所有轮次中累积。跳过、推迟和确认操作都计为“拒绝”用于抑制目的——每个都表示用户决定该发现不值得本轮操作（确认是无修复守卫变体：用户看到没有 suggested_fix 的发现，选择不明确推迟或跳过，而是记录确认；对于轮次到轮次的抑制，这在语义上等同于跳过）。撤回是有条件的（它是重新验证变体：早期决策解决或矛盾了发现；请参阅 references/walkthrough.md 中的“撤回用户早期答案解决的发现”）：仅当用户决策使其退役时——已解决的前提（跳过/推迟）或用户断言的事实——它计为拒绝类。应用触发的撤回从不这样（其解决取决于暂存编辑既落地又语义解决发现，这由第 N+1 轮重新综合检查——不是 R29；抑制它会隐藏失败或无效落地的修复）。已应用的发现保留在应用列表上，以便第 N+1 轮角色可以验证修复已落地（请参阅 references/synthesis-and-presentation.md 中的 R30）。

跨会话持久化超出范围。稍后对同一文档的审查从新的第 1 轮开始，没有携带的启动器，即使先前会话将发现推迟到文档的开放问题部分。

错误处理： 如果子代理失败或超时，使用完成的子代理的发现继续。在覆盖部分注意失败的审查者。不要因单个审查者失败而阻塞整个审查。

调度限制： 即使在最大（7 个代理），使用有界并行调度。如果工具上限低于选定团队大小，排队其余部分并在活动审查者完成时启动它们。

跨模型判断通过

如果条件判断三人组中的任何一个——adversarial-document-reviewer、product-lens-reviewer、security-lens-reviewer——被激活，加载 references/cross-model-review.md 并遵循它进行附加的、非阻塞的同行通过。将主机证明为工具加服务家族，为整个文档解析一个目标和一条具体路由，根据出口允许列表验证每个实际接收者，并在内容离开主机之前披露和制裁该固定路由。cursor 表示 Cursor 默认/自动；composer 表示通过 Cursor 的显式 Composer 家族模型。首先尝试声明的映射；仅在观察到不兼容后，目标绑定的同家族模型覆盖可以适应过时的默认值。切勿静默更改显式模型或接收者，切勿让调度的工人选择更改接收者的回退。

为每个激活的三重透镜启动一个分离的 runner 作业，加上一个 whole-doc 扫描，与进程内审查者同一波，使用参考中的确切调用契约。每个三重同行接收其孪生的相同审查者特定切片；whole-doc 接收完整文档。所有调用使用相同的制裁目标/路由。通过 runner 轮询、收割、归因和清理；失败或超时保持非阻塞并在覆盖中命名。将发现折叠到普通综合中，但协议提升需要工件的顶级 independence_verified: true；false 或缺失的独立性是有用的证据，不是不同模型的佐证。可行性和收敛透镜（coherence、scope-guardian）不运行跨模型。

阶段 3-5：综合、呈现和下一步行动

在所有调度的代理返回后——包括任何跨模型 <reviewer-name>-<provider>.json 返回——读取 references/synthesis-and-presentation.md 了解综合管道（验证、基于锚的门、去重、条件协议提升、解决矛盾、自动提升、按三层路由并带 FYI 小节）、safe_auto 修复应用、无头信封输出以及路由问题的交接。同行发现进入普通综合，但只有具有 independence_verified: true 的工件计为独立审查者用于提升。

对于四选项路由问题和逐条发现走查（交互模式），读取 references/walkthrough.md。对于最佳判断路由、追加到开放问题和走查 Auto-resolve with best judgment on the rest 使用的批量操作预览，读取 references/bulk-preview.md。在代理调度完成之前不要加载这些文件。

---

包含的参考

子代理模板

@./references/subagent-template.md

发现模式

@./references/findings-schema.json

选定的审查者提示资产位于 references/personas/ 下。仅读取为当前审查选择的提示文件。