Back to Details

ce-doc-review

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Document Review

文档审查

Review requirements or plan documents through multi-persona analysis. Dispatches specialized reviewer agents in parallel, auto-applies 
safe_auto
fixes, and routes remaining findings through a four-option interaction (per-finding walk-through, LFG, Append-to-Open-Questions, Report-only) for user decision.
通过多角色分析审查需求或计划文档。并行调度专业审查代理，自动应用
safe_auto
修复，并通过四种交互选项（逐个问题引导、LFG、追加至待解决问题、仅生成报告）将剩余发现交由用户决策。

Interactive mode rules

交互式模式规则

  • Pre-load the platform question tool before any question fires. In Claude Code, 
    AskUserQuestion
    is a deferred tool — its schema is not available at session start. At the start of Interactive-mode work (before the routing question, per-finding walk-through questions, bulk-preview Proceed/Cancel, and Phase 5 terminal question), call 
    ToolSearch
    with query 
    select:AskUserQuestion
    to load the schema. Load it once, eagerly, at the top of the Interactive flow — do not wait for the first question site. On Codex, Gemini, and Pi this preload is not required.
  • The numbered-list fallback applies only when the harness genuinely lacks a blocking question tool — 
    ToolSearch
    returns no match, the tool call explicitly fails, or the runtime mode does not expose it (e.g., Codex edit modes where 
    request_user_input
    is unavailable). A pending schema load is not a fallback trigger; call 
    ToolSearch
    first per the pre-load rule. In genuine-fallback cases, present options as a numbered list and wait for the user's reply — never silently skip the question. Rendering a question as narrative text because the tool feels inconvenient, because the model is in report-formatting mode, or because the instruction was buried in a long skill is a bug. A question that calls for a user decision must either fire the tool or fall back loudly.
  • 在发起任何问题前预加载平台提问工具。在Claude Code中，
    AskUserQuestion
    是延迟加载工具——会话启动时其架构不可用。在交互式模式工作开始时（在路由问题、逐个问题引导、批量预览继续/取消以及阶段5终端问题之前），调用
    ToolSearch
    并传入查询参数
    select:AskUserQuestion
    以加载架构。在交互式流程开始时提前加载一次，不要等待第一个问题出现。在Codex、Gemini和Pi中无需此预加载操作。
  • 编号列表回退仅在工具确实缺少阻塞式提问工具时适用——
    ToolSearch
    未返回匹配结果、工具调用明确失败或运行时模式未暴露该工具（例如Codex编辑模式中
    request_user_input
    不可用）。架构加载中不触发回退；需先按照预加载规则调用
    ToolSearch
    。在真正需要回退的情况下，将选项以编号列表形式呈现并等待用户回复——绝不能静默跳过问题。因工具使用不便、模型处于报告格式化模式或指令被淹没在冗长技能中而将问题以叙述文本形式呈现属于错误。需要用户决策的问题必须要么调用工具，要么明确触发回退。

Phase 0: Detect Mode

阶段0：模式检测

Check the skill arguments for 
mode:headless
. Arguments may contain a document path, 
mode:headless
, or both. Tokens starting with 
mode:
are flags, not file paths — strip them from the arguments and use the remaining token (if any) as the document path for Phase 1.
If 
mode:headless
is present, set headless mode for the rest of the workflow.
Headless mode changes the interaction model, not the classification boundaries. ce-doc-review still applies the same judgment about which tier each finding belongs in. The only difference is how non-safe_auto findings are delivered:
  • safe_auto
    fixes are applied silently (same as interactive)
  • gated_auto
    , 
    manual
    , and FYI findings are returned as structured text for the caller to handle — no blocking-question prompts, no interactive routing
  • Phase 5 returns immediately with "Review complete" (no routing question, no terminal question)
The caller receives findings with their original classifications intact and decides what to do with them.
Callers invoke headless mode by including 
mode:headless
in the skill arguments, e.g.:
Skill("ce-doc-review", "mode:headless docs/plans/my-plan.md")
If 
mode:headless
is not present, the skill runs in its default interactive mode with the routing question, walk-through, and bulk-preview behaviors documented in 
references/walkthrough.md
and 
references/bulk-preview.md
.
检查技能参数中是否包含
mode:headless
。参数可能包含文档路径、
mode:headless
或两者兼具。以
mode:
开头的标记为标志，而非文件路径——从参数中移除这些标记，并将剩余标记（如有）作为阶段1的文档路径。
如果存在
mode:headless
，则在后续工作流中设置无头模式。
无头模式仅改变交互模型，不改变分类边界。ce-doc-review仍会对每个发现的层级做出相同判断。唯一区别在于非
safe_auto
发现的交付方式：
  • safe_auto
    修复会静默应用（与交互式模式相同）
  • gated_auto
    、
    manual
    和FYI发现会以结构化文本形式返回，由调用方自行处理——无阻塞式问题提示，无交互式路由
  • 阶段5直接返回“审查完成”（无路由问题，无终端问题）
调用方会收到保留原始分类的发现，并自行决定如何处理。
调用方通过在技能参数中包含
mode:headless
来启用无头模式，例如：
Skill("ce-doc-review", "mode:headless docs/plans/my-plan.md")
如果不存在
mode:headless
，则技能以默认交互式模式运行，具备路由问题、引导流程和批量预览行为，相关说明见
references/walkthrough.md
和
references/bulk-preview.md
。

Phase 1: Get and Analyze Document

阶段1：获取并分析文档

If a document path is provided: Read it, then proceed.
If no document is specified (interactive mode): Ask which document to review, or find the most recent in 
docs/brainstorms/
or 
docs/plans/
using a file-search/glob tool (e.g., Glob in Claude Code).
If no document is specified (headless mode): Output "Review failed: headless mode requires a document path. Re-invoke with: Skill("ce-doc-review", "mode:headless <path>")" without dispatching agents.
若提供文档路径：读取文档，然后继续。
若未指定文档（交互式模式）：询问要审查的文档，或使用文件搜索/通配符工具（例如Claude Code中的Glob）在
docs/brainstorms/
或
docs/plans/
中查找最新文档。
若未指定文档（无头模式）：输出“审查失败：无头模式需要文档路径。请重新调用：Skill("ce-doc-review", "mode:headless <path>")”，且不调度代理。

Classify Document Type

文档类型分类

After reading, classify the document:
  • requirements -- from 
    docs/brainstorms/
    , focuses on what to build and why
  • plan -- from 
    docs/plans/
    , focuses on how to build it with implementation details
读取文档后，对其进行分类：
  • requirements（需求文档） -- 来自
    docs/brainstorms/
    ，聚焦于要构建的内容及原因
  • plan（计划文档） -- 来自
    docs/plans/
    ，聚焦于如何构建及实现细节

Select Conditional Personas

选择条件角色

Analyze the document content to determine which conditional personas to activate. Check for these signals:
product-lens -- activate when the document makes challengeable claims about what to build and why, or when the proposed work carries strategic weight beyond the immediate problem. The system's users may be end users, developers, operators, maintainers, or any other audience -- the criteria are domain-agnostic. Check for either leg:
Leg 1 — Premise claims: The document stakes a position on what to build or why that a knowledgeable stakeholder could reasonably challenge -- not merely describing a task or restating known requirements:
  • Problem framing where the stated need is non-obvious or debatable, not self-evident from existing context
  • Solution selection where alternatives plausibly exist (implicit or explicit)
  • Prioritization decisions that explicitly rank what gets built vs deferred
  • Goal statements that predict specific user outcomes, not just restate constraints or describe deliverables
Leg 2 — Strategic weight: The proposed work could affect system trajectory, user perception, or competitive positioning, even if the premise is sound:
  • Changes that shape how the system is perceived or what it becomes known for
  • Complexity or simplicity bets that affect adoption, onboarding, or cognitive load
  • Work that opens or closes future directions (path dependencies, architectural commitments)
  • Opportunity cost implications -- building this means not building something else
design-lens -- activate when the document contains:
  • UI/UX references, frontend components, or visual design language
  • User flows, wireframes, screen/page/view mentions
  • Interaction descriptions (forms, buttons, navigation, modals)
  • References to responsive behavior or accessibility
security-lens -- activate when the document contains:
  • Auth/authorization mentions, login flows, session management
  • API endpoints exposed to external clients
  • Data handling, PII, payments, tokens, credentials, encryption
  • Third-party integrations with trust boundary implications
scope-guardian -- activate when the document contains:
  • Multiple priority tiers (P0/P1/P2, must-have/should-have/nice-to-have)
  • Large requirement count (>8 distinct requirements or implementation units)
  • Stretch goals, nice-to-haves, or "future work" sections
  • Scope boundary language that seems misaligned with stated goals
  • Goals that don't clearly connect to requirements
adversarial -- activate when the document contains:
  • More than 5 distinct requirements or implementation units
  • Explicit architectural or scope decisions with stated rationale
  • High-stakes domains (auth, payments, data migrations, external integrations)
  • Proposals of new abstractions, frameworks, or significant architectural patterns
分析文档内容以确定要激活哪些条件角色。检查以下信号：
product-lens（产品视角） -- 当文档对要构建的内容及原因提出可质疑的主张，或拟议工作具有超出当前问题的战略意义时激活。系统用户可能是终端用户、开发者、运维人员、维护人员或其他受众——标准与领域无关。满足以下任一条件即可激活：
条件1 — 前提主张：文档对要构建的内容或原因持某种立场，而知情利益相关者可合理提出质疑——并非仅仅描述任务或重述已知需求：
  • 问题框架中所述需求不明显或存在争议，无法从现有背景中自证
  • 解决方案选择中存在合理的替代方案（隐含或明确）
  • 优先级决策明确划分了要构建的内容与延迟的内容
  • 目标陈述预测特定用户成果，而非仅重述约束条件或描述交付物
条件2 — 战略权重：拟议工作可能影响系统发展轨迹、用户认知或竞争定位，即使前提合理：
  • 改变系统认知或使其具备特定特色的变更
  • 影响采用率、入门难度或认知负荷的复杂度/简洁性决策
  • 开启或关闭未来方向的工作（路径依赖、架构承诺）
  • 机会成本影响——构建此内容意味着无法构建其他内容
design-lens（设计视角） -- 当文档包含以下内容时激活：
  • UI/UX参考、前端组件或视觉设计语言
  • 用户流程、线框图、屏幕/页面/视图提及
  • 交互描述（表单、按钮、导航、模态框）
  • 响应式行为或可访问性参考
security-lens（安全视角） -- 当文档包含以下内容时激活：
  • 认证/授权提及、登录流程、会话管理
  • 向外部客户端暴露的API端点
  • 数据处理、PII（个人可识别信息）、支付、令牌、凭证、加密
  • 具有信任边界影响的第三方集成
scope-guardian（范围守护者） -- 当文档包含以下内容时激活：
  • 多个优先级层级（P0/P1/P2、必须具备/应该具备/可以具备）
  • 大量需求（超过8个不同需求或实现单元）
  • 扩展目标、额外需求或“未来工作”章节
  • 与既定目标不一致的范围边界表述
  • 与需求无明确关联的目标
adversarial（对抗性审查） -- 当文档包含以下内容时激活：
  • 超过5个不同需求或实现单元
  • 具有明确理由的架构或范围决策
  • 高风险领域（认证、支付、数据迁移、外部集成）
  • 新抽象、框架或重要架构模式的提案

Phase 2: Announce and Dispatch Personas

阶段2：公告并调度角色

Announce the Review Team

公告审查团队

Tell the user which personas will review and why. For conditional personas, include the justification:
Reviewing with:
- ce-coherence-reviewer (always-on)
- ce-feasibility-reviewer (always-on)
- ce-scope-guardian-reviewer -- plan has 12 requirements across 3 priority levels
- ce-security-lens-reviewer -- plan adds API endpoints with auth flow
告知用户将由哪些角色进行审查及原因。对于条件角色，需包含理由：
参与审查的角色：
- ce-coherence-reviewer（始终启用）
- ce-feasibility-reviewer（始终启用）
- ce-scope-guardian-reviewer -- 计划包含3个优先级层级下的12项需求
- ce-security-lens-reviewer -- 计划添加了带认证流程的API端点

Build Agent List

构建代理列表

Always include:
  • ce-coherence-reviewer
  • ce-feasibility-reviewer
Add activated conditional personas:
  • ce-product-lens-reviewer
  • ce-design-lens-reviewer
  • ce-security-lens-reviewer
  • ce-scope-guardian-reviewer
  • ce-adversarial-document-reviewer
始终包含：
  • ce-coherence-reviewer
  • ce-feasibility-reviewer
添加已激活的条件角色：
  • ce-product-lens-reviewer
  • ce-design-lens-reviewer
  • ce-security-lens-reviewer
  • ce-scope-guardian-reviewer
  • ce-adversarial-document-reviewer

Dispatch

调度

Dispatch all agents in parallel using the platform's subagent primitive (e.g., 
Agent
in Claude Code, 
spawn_agent
in Codex, 
subagent
in Pi via the 
pi-subagents
extension). Omit the 
mode
parameter so the user's configured permission settings apply. Each agent receives the prompt built from the subagent template included below with these variables filled:
VariableValue
{persona_file}
Full content of the agent's markdown file
{schema}
Content of the findings schema included below
{document_type}
"requirements" or "plan" from Phase 1 classification
{document_path}
Path to the document
{document_content}
Full text of the document
{decision_primer}
Cumulative prior-round decisions in the current session, or an empty 
<prior-decisions>
block on round 1. See "Decision primer" below.
Pass each agent the full document — do not split into sections.
使用平台的子代理原语（例如Claude Code中的
Agent
、Codex中的
spawn_agent
、Pi中通过
pi-subagents
扩展实现的
subagent
）并行调度所有代理。省略
mode
参数，以便应用用户配置的权限设置。每个代理都会收到根据以下子代理模板填充变量后生成的提示：
变量值
{persona_file}
代理的markdown文件完整内容
{schema}
下方包含的发现架构内容
{document_type}
阶段1分类得到的“requirements”或“plan”
{document_path}
文档路径
{document_content}
文档完整文本
{decision_primer}
当前会话中累积的前一轮决策，或第一轮时的空
<prior-decisions>
块。详见下方“决策基础”。
向每个代理传递完整文档——不要拆分成分段。

Decision primer

决策基础

On round 1 (no prior decisions), set 
{decision_primer}
to:
<prior-decisions>
Round 1 — no prior decisions.
</prior-decisions>
On round 2+ (after one or more prior rounds in the current interactive session), accumulate prior-round decisions and render them as:
<prior-decisions>
Round 1 — applied (N entries):
- {section}: "{title}" ({reviewer}, {confidence})
  Evidence: "{evidence_snippet}"

Round 1 — rejected (M entries):
- {section}: "{title}" — Skipped because {reason}
  Evidence: "{evidence_snippet}"
- {section}: "{title}" — Deferred to Open Questions because {reason or "no reason provided"}
  Evidence: "{evidence_snippet}"
- {section}: "{title}" — Acknowledged without applying because {reason or "no suggested_fix — user acknowledged"}
  Evidence: "{evidence_snippet}"

Round 2 — applied (N entries):
...
</prior-decisions>
Each entry carries an 
Evidence:
line because synthesis R29 (rejected-finding suppression) and R30 (fix-landed verification) both use an evidence-substring overlap check as part of their matching predicate — without the evidence snippet in the primer, the orchestrator cannot compute the 
>50%
overlap test and has to fall back to fingerprint-only matching, which either re-surfaces rejected findings or suppresses too aggressively. The 
{evidence_snippet}
is the first evidence quote from the finding, truncated to the first ~120 characters (preserving whole words at the boundary) and with internal quotes escaped. If a finding has multiple evidence entries, use the first one; the rest live in the run artifact and are not needed for the overlap check.
Accumulate across all rounds in the current session. Skip, Defer, and Acknowledge actions all count as "rejected" for suppression purposes — each signals the user decided the finding wasn't worth actioning this round (Acknowledge is the no-fix-guard variant: the user saw a finding with no 
suggested_fix
, chose not to defer or skip explicitly, and recorded acknowledgement instead; for round-to-round suppression that is semantically equivalent to Skip). Applied findings stay on the applied list so round-N+1 personas can verify fixes landed (see R30 in 
references/synthesis-and-presentation.md
).
Cross-session persistence is out of scope. A new invocation of ce-doc-review on the same document starts with a fresh round 1 and no carried primer, even if prior sessions deferred findings into the document's Open Questions section.
Error handling: If an agent fails or times out, proceed with findings from agents that completed. Note the failed agent in the Coverage section. Do not block the entire review on a single agent failure.
Dispatch limit: Even at maximum (7 agents), use parallel dispatch. These are document reviewers with bounded scope reading a single document -- parallel is safe and fast.
第一轮（无先前决策）时，将
{decision_primer}
设置为：
<prior-decisions>
第一轮 — 无先前决策。
</prior-decisions>
第二轮及以后（当前交互式会话中经过一轮或多轮后），累积前一轮决策并格式化为：
<prior-decisions>
第一轮 — 已应用（N项）：
- {section}: "{title}" ({reviewer}, {confidence})
  证据: "{evidence_snippet}"

第一轮 — 已拒绝（M项）：
- {section}: "{title}" — 跳过原因：{reason}
  证据: "{evidence_snippet}"
- {section}: "{title}" — 推迟至待解决问题，原因：{reason或“未提供原因”}
  证据: "{evidence_snippet}"
- {section}: "{title}" — 已确认但未应用，原因：{reason或“无建议修复方案——用户已确认”}
  证据: "{evidence_snippet}"

第二轮 — 已应用（N项）：
...
</prior-decisions>
每个条目都包含
证据:
行，因为合成规则R29（已拒绝发现抑制）和R30（修复落地验证）均使用证据子串重叠检查作为匹配谓词的一部分——若基础中无证据片段，编排器无法计算
>50%
重叠测试，只能回退到仅指纹匹配，这要么会重新显示已拒绝的发现，要么会过度抑制。
{evidence_snippet}
是发现中的第一条证据引用，截断至前约120个字符（在边界处保留完整单词）并转义内部引号。若发现包含多条证据，使用第一条；其余证据存储在运行工件中，重叠检查无需使用。
累积当前会话中的所有轮次结果。跳过、推迟和确认操作均视为“已拒绝”以用于抑制目的——每个操作都表明用户决定本轮不对该发现采取行动（确认是无修复方案的变体：用户看到无
suggested_fix
的发现，选择不明确推迟或跳过，而是记录确认；对于轮次间抑制，这在语义上等同于跳过）。已应用的发现保留在已应用列表中，以便第N+1轮角色验证修复是否落地（详见
references/synthesis-and-presentation.md
中的R30）。
跨会话持久化不在范围内。即使先前会话已将发现推迟至文档的待解决问题部分，同一文档的新ce-doc-review调用仍会从第一轮开始，无携带的基础内容。
错误处理：若代理失败或超时，继续使用已完成代理的发现。在覆盖范围部分注明失败的代理。不要因单个代理失败而阻塞整个审查。
调度限制：即使达到最大数量（7个代理），仍使用并行调度。这些是范围有限的文档审查代理，仅读取单个文档——并行调度安全且高效。

Phases 3-5: Synthesis, Presentation, and Next Action

阶段3-5：合成、展示与下一步操作

After all dispatched agents return, read 
references/synthesis-and-presentation.md
for the synthesis pipeline (validate, anchor-based gate, dedup, cross-persona agreement promotion, resolve contradictions, auto-promotion, route by three tiers with FYI subsection), 
safe_auto
fix application, headless-envelope output, and the handoff to the routing question.
For the four-option routing question and per-finding walk-through (interactive mode), read 
references/walkthrough.md
. For the bulk-action preview used by LFG, Append-to-Open-Questions, and walk-through 
LFG-the-rest
, read 
references/bulk-preview.md
. Do not load these files before agent dispatch completes.
所有调度的代理返回结果后，阅读
references/synthesis-and-presentation.md
了解合成流程（验证、基于锚点的门控、去重、跨角色一致性提升、解决矛盾、自动升级、按三个层级路由并包含FYI子部分）、
safe_auto
修复应用、无头模式输出以及路由问题的交接。
关于交互式模式下的四选项路由问题和逐个问题引导，阅读
references/walkthrough.md
。关于LFG、追加至待解决问题和引导流程中的“LFG-the-rest”所使用的批量操作预览，阅读
references/bulk-preview.md
。不要在代理调度完成前加载这些文件。

Included References

包含的参考资料

Subagent Template

子代理模板

@./references/subagent-template.md
@./references/subagent-template.md

Findings Schema

发现架构

@./references/findings-schema.json
@./references/findings-schema.json