Back to Details

document-review

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Document Review

文档审查

Improve brainstorm or plan documents through structured review.
通过结构化审查优化头脑风暴或计划类文档。

Step 1: Get the Document

步骤1：获取文档

If a document path is provided: Read it, then proceed to Step 2.
If no document is specified: Ask which document to review, or look for the most recent brainstorm/plan in 
docs/brainstorms/
or 
docs/plans/
.
若提供了文档路径： 读取文档，然后进入步骤2。
若未指定文档： 询问需要审查的文档，或在
docs/brainstorms/
或
docs/plans/
目录中查找最新的头脑风暴/计划文档。

Step 2: Assess

步骤2：评估

Read through the document and ask:
  • What is unclear?
  • What is unnecessary?
  • What decision is being avoided?
  • What assumptions are unstated?
  • Where could scope accidentally expand?
  • Is this technically feasible with the current architecture?
  • Are there security implications in what's proposed?
These questions surface issues. Don't fix yet--just note what you find.
通读文档并思考以下问题：
  • 哪些内容表述模糊？
  • 哪些内容是多余的？
  • 回避了哪些决策？
  • 存在哪些未明确说明的假设？
  • 哪些地方可能会意外扩大范围？
  • 基于当前架构，方案在技术上是否可行？
  • 提议的内容是否存在安全隐患？
这些问题可以暴露文档中的问题。此时无需修复，只需记录发现的问题。

Step 3: Activate Review Lenses

步骤3：启用审查视角

Based on the document's content, activate specialized review perspectives. Scan for signals and apply matching lenses:
LensSignalsWhat it checks
ProductUser-facing features, customer language, market claims, scope decisionsProblem framing, value proposition clarity, whether scope matches stated goals
DesignUI/UX references, user flows, wireframes, interaction descriptionsFlow completeness, interaction gaps, accessibility considerations
SecurityAuth/authorization, API endpoints, PII, payments, tokens, encryptionAuth model gaps, data exposure risks, missing threat considerations
Scope guardianMultiple priority tiers (P0/P1/P2), large requirement count (>8), stretch goalsScope creep, premature abstractions, features disguised as requirements
Adversarial>5 distinct requirements, explicit architectural decisions, high-stakes domainsUnstated assumptions, optimistic estimates, single points of failure, missing failure modes
Activate a lens when ANY of its signals match. Most documents trigger 1-2 lenses; brainstorm notes may trigger none. When a lens is active, weave its checks into the assessment and evaluation steps rather than running it as a separate pass.
根据文档内容，启用专门的审查视角。扫描文档中的信号并匹配对应的视角：
视角触发信号检查内容
产品视角面向用户的功能、客户语言、市场声明、范围决策问题框架、价值主张清晰度、范围是否与既定目标匹配
设计视角UI/UX参考、用户流程、线框图、交互描述流程完整性、交互缺口、可访问性考量
安全视角身份验证/授权、API端点、PII、支付功能、令牌、加密身份验证模型缺口、数据泄露风险、缺失的威胁考量
范围守护者视角多优先级层级（P0/P1/P2）、需求数量较多（>8）、延伸目标范围蔓延、过早抽象、伪装成需求的功能
对抗性视角超过5项不同需求、明确的架构决策、高风险领域未明确的假设、乐观估算、单点故障、缺失的故障模式
当视角的任意触发信号匹配时，即启用该视角。大多数文档会触发1-2个视角；头脑风暴笔记可能不会触发任何视角。启用视角后，将其检查内容融入评估和评价步骤，而非单独进行一轮审查。

Step 4: Evaluate

步骤4：评价

Score the document against these criteria:
CriterionWhat to Check
ClarityProblem statement is clear, no vague language ("probably," "consider," "try to")
CompletenessRequired sections present, constraints stated, open questions flagged
SpecificityConcrete enough for next step (brainstorm → can plan, plan → can implement)
YAGNINo hypothetical features, simplest approach chosen
If invoked within a workflow (after 
/ia-brainstorm
or 
/ia-plan
), also check:
  • User intent fidelity -- Document reflects what was discussed, assumptions validated
根据以下标准为文档打分：
标准检查内容
清晰度问题陈述清晰，无模糊表述（如“可能”、“考虑”、“尝试”）
完整性包含必填章节、明确约束条件、标记未解决问题
具体性内容足够具体，可推进至下一步（头脑风暴→制定计划，计划→实施）
YAGNI无假设性功能，选择最简方案
如果是在工作流中调用（
/ia-brainstorm
或
/ia-plan
之后），还需检查：
  • 用户意图保真度——文档反映了讨论内容，假设已验证

Step 5: Identify the Critical Improvement

步骤5：确定关键改进点

Among everything found in Steps 2-4, does one issue stand out? If something would significantly improve the document's quality, this is the "must address" item. Highlight it prominently.
在步骤2-4中发现的所有问题里，是否有一个突出的问题？如果某个问题的解决能显著提升文档质量，那么这就是“必须解决”的事项。需重点突出该事项。

Step 6: Make Changes

步骤6：进行修改

Present your findings, then:
  1. Auto-fix minor issues (vague language, formatting) without asking
  2. Ask approval before substantive changes (restructuring, removing sections, changing meaning)
  3. Update the document inline--no separate files, no metadata sections
先呈现发现的问题，然后：
  1. 自动修复 minor issues（模糊表述、格式问题），无需询问
  2. 请求批准 再进行实质性修改（重构、删除章节、改变语义）
  3. 内联更新 文档——不创建单独文件，不添加元数据章节

Simplification Guidance

简化指导原则

Simplification is purposeful removal of unnecessary complexity, not shortening for its own sake.
Simplify when:
  • Content serves hypothetical future needs, not current ones
  • Sections repeat information already covered elsewhere
  • Detail exceeds what's needed to take the next step
  • Abstractions or structure add overhead without clarity
Don't simplify:
  • Constraints or edge cases that affect implementation
  • Rationale that explains why alternatives were rejected
  • Open questions that need resolution
简化是有目的地移除不必要的复杂性，而非单纯缩短内容。
需简化的场景：
  • 内容服务于假设性未来需求，而非当前需求
  • 章节重复了其他地方已涵盖的信息
  • 细节超出了推进下一步所需的程度
  • 抽象或结构增加了负担却未提升清晰度
无需简化的场景：
  • 影响实施的约束条件或边缘情况
  • 解释为何拒绝替代方案的理由
  • 需要解决的未明确问题

Step 7: Reader Test (Optional)

步骤7：读者测试（可选）

For standalone documents that must be self-contained (onboarding guides, ADRs, external-facing docs), dispatch a zero-context sub-agent to simulate a first-time reader. The sub-agent has no conversation history — it sees only what a future reader would see.
How to run the test:
  1. Predict 5-10 reader questions from the document's stated goals — one per major section or decision. Mix three kinds:
    • Concrete retrieval: "What command sets up the dev environment?"
    • Decision rationale: "Why did we pick X over Y?"
    • Ambiguity probe: "Could a reader interpret <specific phrase> in more than one way?"
  2. Dispatch a fresh sub-agent with the document attached and the questions. No prior context, no session history.
  3. Compare the sub-agent's answers against author intent. Also ask the sub-agent directly: "What feels ambiguous? What prior knowledge does this assume? Are there internal contradictions?"
Interpret results:
  • Correct, confident answers → document is self-contained for that question.
  • Wrong answer with high confidence → document actively misleads. Highest-priority fix.
  • Hedged or "insufficient information" → the document has a gap the author didn't notice. Fill it.
  • Sub-agent flags ambiguity the author didn't intend → reword for precision.
Skip for context-dependent docs (brainstorm notes, plan files, internal working docs) where the reader will always have prior context. The sub-agent test only adds value when the real reader has no other channel.
对于必须具备自包含性的独立文档（入职指南、ADR、对外文档），派遣一个无上下文的sub-agent模拟首次读者。该sub-agent无对话历史——仅能看到未来读者会看到的内容。
测试运行方式：
  1. 预测5-10个读者问题 基于文档的既定目标——每个主要章节或决策对应一个问题。包含三种类型：
    • 具体检索类：“设置开发环境的命令是什么？”
    • 决策理由类：“我们为何选择X而非Y？”
    • 模糊性探查类：“读者是否可能对<特定表述>产生多种解读？”
  2. 派遣全新的sub-agent 附上文档和问题。无前置上下文，无会话历史。
  3. 对比sub-agent的答案与作者意图。同时直接询问sub-agent：“哪些内容感觉模糊？文档假设读者具备哪些前置知识？是否存在内部矛盾？”
结果解读：
  • 答案正确且自信→文档针对该问题具备自包含性。
  • 答案错误却自信→文档存在误导性。需优先修复。
  • 答案含糊或“信息不足”→文档存在作者未察觉的缺口。需填补。
  • sub-agent指出作者未预期的模糊点→重新表述以提升精准度。
对于依赖上下文的文档（头脑风暴笔记、计划文件、内部工作文档），读者始终具备前置知识，可跳过此测试。仅当真实读者无其他获取信息渠道时，sub-agent测试才会带来价值。

Step 8: Offer Next Action

步骤8：提供下一步行动选项

After changes are complete, ask:
  1. Refine again - Another review pass
  2. Review complete - Document is ready
修改完成后，询问：
  1. 再次优化 - 进行另一轮审查
  2. 审查完成 - 文档已就绪

Iteration Guidance

迭代指导原则

After 2 refinement passes, recommend completion--diminishing returns are likely. If the user wants to continue, allow up to 4 passes total. After 4, stop and report "review converged -- further changes require new direction." Do not continue past 4 even on user request without a fresh framing.
Return control to the caller (workflow or user) after selection.
经过2轮优化后，建议结束审查——后续收益可能递减。若用户希望继续，最多允许4轮迭代。4轮后，停止并报告“审查已收敛——进一步修改需要新的方向”。即使用户要求，若无新的框架，也不得继续超过4轮。
用户选择后，将控制权交回调用方（工作流或用户）。

Constraints

约束条件

  • Fix targeted sections, don't rewrite the whole document. If the structure is fundamentally broken, surface the structural problem and ask for permission to restructure.
  • Flag missing sections in your review, but don't add them. The user decides what to include.
  • Keep changes minimal. If a paragraph needs tightening, tighten it. Don't expand scope.
  • Review inline. No separate review files or metadata sections.
  • 仅针对目标章节进行修复，不要重写整个文档。如果结构存在根本性问题，需指出结构问题并请求重构权限。
  • 在审查中标记缺失的章节，但不要自行添加。由用户决定内容的取舍。
  • 保持修改最小化。若段落需要精简，就精简它。不要扩大范围。
  • 内联进行审查。不创建单独的审查文件或元数据章节。

Success Criteria

成功标准

  • Document read and scored on all four quality criteria
  • Relevant review lenses activated and checks applied
  • Critical improvements identified with specific suggestions
  • User presented with clear next-action choice (refine or complete)
  • Revised document saved if changes were approved
  • 已通读文档并基于所有四项质量标准打分
  • 已启用相关审查视角并完成对应检查
  • 已确定关键改进点并提供具体建议
  • 已向用户呈现明确的下一步行动选项（优化或完成）
  • 若修改获得批准，已保存修订后的文档