reviewing-document-set

reviewing-document-set — SKILL.md

变体： 标准 · 适用场景： 将一组已完成的文档视为一个语料库进行评判——检查它们是否相互连贯并且已准备好用于规划，然后输出 VERDICT: approve|revise，并附上按文档归属的发现。

概述

此技能是针对一组已完成的相关文档的语料库级验收关卡。由审阅整组文档的审阅者加载，用来回答一个问题：这些文档是否构成一个连贯的整体，能够延续项目意图，并足以据此规划和构建？ 它应用一份固定的八维跨文档检查清单，然后输出一个可供机器解析的判定，以及按文档归属、可供编写者采取行动的发现。

它是单文档审阅的补充——每份文档自身的质量关卡都已在更早阶段运行。此技能绝不重新评判单份文档的内部质量；它只判断这些文档作为一组彼此之间的关系。它仅用于审阅：不会编写、修复或重写任何内容。

何时启用

• 一组已完成的相关项目文档需要在下游规划前，就相互连贯性作出接受或修订的决定。
• 在每份文档都通过各自类型审阅后，你需要作为语料库的独立关卡。
• 在发生变更后重新审阅语料库——无论是编写者修复了先前判定为 revise 的问题，还是一份（或少数几份）文档独立发生了变化。两种情况都执行维度 7（修订 / 限定差异的重新审阅）：只重新验证变更涉及的关系边，而非整个语料库。

请勿在以下情况启用：

• 你正在评判单份文档的内部质量——请使用对应的单文档审阅（例如，对单份设计文档进行设计审阅）。
• 你正在编写或修复文档——此技能仅用于审阅。
• 只有一份文档——没有跨文档关系可供评判。

工作流

该方法包含八个维度，然后给出判定。先阅读每份文档。

根据语料库规模调整审计程度（比例原则）。 跨文档审计的深度，以及适用的维度，都应随语料库规模而调整。一组规模较小且连贯的文档（2–3 份文档、很少的跨文档关系边）应当予以批准；不要为了据此判定为修订而凭空制造 RTM 式的繁文缛节。几个维度在常见情况下明确标为不适用：对于没有先前版本或明确变更的全新首轮文档集，维度 7（修订）不适用；对于只有一个版本的文档集，维度 8（版本偏差）不适用。对内容单薄或首轮的语料库进行重量级审计，会导致错误的修订判定。

步骤 1 — 确定方向

找出最上游的文档（源头简报 / 需求文档）——它是锚定“向下游传递”检查的可追溯性根节点。记录每份文档声明的上游依赖项。假定每份文档都已通过自身关卡，因此你只需查找跨文档缺陷。评判交给你的这组文档——不需要单独列出“预期”文档。还要记录随文档集一并提供的任何明确变更（差异、版本升级、变更日志）——只要存在此类信息，就会触发修订重新审阅（维度 7）；若不存在，则表示这是全新首轮审阅（维度 7 不适用）。

步骤 2 — 评判八个维度

针对每个维度，收集发现（缺陷始终存在于文档之间）：

1. 跨文档一致性（包括关键术语）。 同一事实、数字、决策、范围边界或命名实体，在所有涉及它的文档中都应采用相同表述。分为两类问题：实质性不一致（数值／决策／范围的表述不同）和关键术语不一致（同一核心实体在不同文档中名称不同——这里称为“成员”，那里称为“账户”，且没有说明它们是同一实体）。两类都要标出。不要标出文风、语气或无害的同义词差异。
2. 完整性与可追溯性（以根文档为锚点）。 根文档中的每项目标／要求，都应在需要对其展开说明或予以实现的文档中得到延续；不得悄然遗漏。标出遗漏的要求（根文档中有，下游文档中没有）、孤立文档（没有文档引用它，它也不引用任何上游文档），以及尚未解决的 TBD／占位内容意图。
3. 矛盾检测。 任意两份文档都不得断言无法同时为真的事实／决策。这是“一致性”最严格的情形——逻辑上不相容，而不只是措辞不同。
4. 依赖完整性。 每份文档都应忠实地展开其声明的上游文档——实体、决策和范围保持一致，只增加细节，不得与之矛盾或悄然重新界定范围。
5. 避免不必要的重复。 属于某份文档的事实／决策／定义应只在该文档中出现一次，其他地方应引用，而非复制，以免副本逐渐不一致。标出内容不一致的重复（同一内容在两处表述却不一致）或大量且无明确归属、可能导致不一致的冗余。
6. 达到可规划状态。 综合来看，这组文档是否充分且连贯，足以让规划人员据此制定合理的里程碑，而无需再询问？ 将就绪定义的核心要求作为“阻碍规划”的具体判定标准：已明确依赖项（文档集依赖的每项跨文档或外部依赖，都须在文档集中某处标明——已命名但从未说明的依赖项构成阻碍）；某处有可测试的验收标准（每项关键要求都须在文档集中的某份文档里有可测试的验收标准——要求由整个文档集承载，而非仅由单份文档承载）；以及没有阻碍规划的 TBD（没有后续阶段所依赖但尚未解决的决策）。还要标出被引用但缺失的关键文档——即已提交的文档集自身引用了某份文档，却未包含该文档（例如，api-spec 写着“参见 data-model”，但文档集中没有 data-model；三份文档都依赖某个安全模型，却没有任何文档对其作出规定）。根据文档集内部悬而未决的引用推断这一缺口——绝不可要求项目可能并不需要的“理想清单”中的文档（例如，无状态 CLI 工具没有 data-model 并非缺陷）。这就是 approve 与 revise 的区别。
7. 修订／仅针对变更范围复审。 仅当文档集中的某份文档发生变更时适用（提交的内容注明了变更、版本升级或更新日志）；首次评审绿地文档集时为 n/a。有两种触发情形，但采用同一方法：变更可能是 (a) 编写者修复先前的 revise，也可能是 (b) 上游文档独立变更。无论哪种情形，都应：(1) 确认发生变更的文档；(2) 追踪变更对那些声明该文档为上游文档的文档造成的影响（其下游文档——存在风险的依赖边）；(3) 检查变更传播情况——对每条受影响的依赖边，检查变更是否已传递至下游文档，还是下游文档现已过时；(4) 仅针对变更范围复审——只重新验证受影响的依赖边及其二阶影响；不要重新审查未变更且原本一致的关系。未受到变更影响的下游文档也应作为问题标出。**“已变更但未注明变更内容”的情形：**如果文档集明显发生了变更，却未提交变更说明，则动态追踪为 n/a——在完整评审中依靠维度 8 的静态偏差检查，发现可能过时的下游文档。
8. 版本偏差（过时的交叉引用）。 对每个明确的交叉引用（文档 A 引用文档 B 中的决策／数值／实体／版本），确认 A 反映的是 B 的当前状态，而非已被取代的状态（A 展开的是 B 的 v1 决策，而 B 已更新至 v2；A 使用了 B 后来已重命名的实体）。重叠防护（不要重复标出）：只有涉及时效性／当前状态的问题，维度 8 才适用——即某份文档基于另一份文档中已被取代的版本／决策编写。若只是数值不一致且不涉及版本，应归入维度 1；若两者绝不可能同时成立，应归入维度 3；若悄然重新界定范围，应归入维度 4。不要在维度 8 下将已在维度 1／3／4 中指出的问题再次标为需要修订。单一版本的文档集（每份文档都是首个版本，不存在可供比较的先前状态）为 n/a。维度 8 是维度 7 中动态变更传播检查的静态对应项：维度 7 在变更已知时发现新产生的偏差；维度 8 则在任何一轮评审中，无论是否有变更信号，都指出偏差。

第 3 步 — 作出判断并输出

权衡各项发现。对于一致、完整、可追溯、当前有效（不存在版本偏差）、变更均已传递（任何变更都已同步）且可进入规划阶段的文档集，予以通过——不要因小问题而对一套协调一致的文档做不必要的修改；也不要因文档集较精简（边数较少）、只有一个版本，或属于绿地项目的首次审查，就要求补上按比例而言不适用的维度（7、8）。发现任何真实且明确指出的跨文档缺口时，要求修改。按以下输出格式输出结果。

规则

硬性规则（绝不违反）：

• 整个文档集只能有一个最终判定。 结尾必须恰好有一行，内容为 VERDICT: approve 或 VERDICT: revise，且判定对象是整个文档集。绝不要为每份文档分别给出判定（调用方通常只读取最后一行 VERDICT:，因此多个判定会导致结果出错）。
• 逐份文档以方括号标注归属。 每条发现都必须以受影响的文档 ID（用方括号括起）开头，然后说明这些文档之间的问题以及如何协调：- [d-prd, d-arch] auth model differs (PRD: OAuth, arch doc: SAML) — pick one and align both. 单项不一致可涉及多个 ID；请明确哪些文档需要修改。这样调用方就能将每项修复任务分配给相应的文档负责人。
• 只检查跨文档问题。 绝不要重新评判单份文档的内部质量——那是先前独立的审核环节。
• 评审提交的文档集。 不要要求提供单独的预期文档清单；交给你评审的文档集就是本次评审的对象。
• 不要误判为需修改。 对协调一致的文档集予以通过；只有存在真实且明确指出的缺口时才要求修改，并确保发现一次即可执行（说明问题、涉及哪些文档，以及如何协调）。
• 仅作评审。 绝不撰写、修复或改写文档；只报告发现，由文档编写者修改。

易错点

• 不要把命名不一致误判为矛盾。 同一实体有不同名称（维度 1）不等于存在无法同时成立的两项陈述（维度 3）。应正确分类——两者所需的修复方式不同。
• 避免偏离到单文档评审。 PRD 写得好不好属于单文档审核环节的职责；在此处只需判断 PRD 是否与其他文档一致，并已体现在其他文档中。
• “每份文档都没问题，所以整个文档集也没问题。” 单独看都正确的文档，彼此仍可能存在分歧——一致性取决于文档之间的关系，而非各自本身。
• 只检查两两关系会漏掉已丢失的需求。 如果某项需求在所有下游文档中都被遗漏，就没有文档对可供检查；只有以根文档为锚点的可追溯性检查才能发现这一问题。
• 逐份文档给出判定。 虽然有逐份文档的发现，但分别给出判定会影响只读取最后一行判定的调用方。判定只能有一个；发现中标注归属即可。
• 不要在版本偏差问题上重复标记（与维度 8 重叠）。 过时的交叉引用属于时效性缺陷（维度 8）——不要再将其作为一般不一致（1）、矛盾（3）或依赖关系缺陷（4）标记。一个缺陷只归入一个维度；“已被取代的版本/决策”归维度 8。
• 不要把修订后的运行当作完整重审。 文档变更后重新验证整个文档集，而非只检查变更影响的关系，既浪费时间，也容易导致误判为需修改——维度 7 的范围应仅限变更部分。反之，如果文档集明显已变更，但没有提供变更说明，则动态追踪不适用——应依靠维度 8，不要臆造变更历史。
• 不要依据外部清单要求提供文档。 只有当文档集本身引用了缺失文档时，“缺少文档”才是合理的发现（维度 6：引用但未提供）。要求提供项目可能不需要的文档（例如无状态 CLI 的数据模型）属于臆造——这里没有清单。

反模式

• 每份文档各自给出结论，而不是针对整个文档集给出一个结论。
• 用自由文本归因（“PRD 和架构文档存在分歧”），却不提供方括号括起的 ID——调用方无法按文档采取行动。
• 把风格差异——同义词、语气、格式——标记为不一致。
• 只因文档数量看似齐全就草率通过，却没有追踪需求或比较决策。
• 重写文档，而不是返回发现项。
• 错误地要求修订文档集：对于较薄、只有单一版本或绿地项目的文档集，因其缺少按比例不适用的维度（7 修改、8 版本偏差）而要求修订——比例性评估针对的是整个文档集，而不是固定清单。

输出

一份发现报告：包含零条或多条归因到具体文档的发现项（每条以 - [id, …] 开头），后接且仅有一个终结标记 VERDICT: approve|revise。如果结论是 revise，这些发现项就是调用方据此为每份受影响文档安排一项修复的可执行清单。抽象层面的使用者是负责分派修复任务的编排器，以及负责修订的产出方。

相关内容

• 单文档设计审查技能——逐文档对应技能；本技能是其文档集层面的补充，应在每份文档通过各自的关卡后运行。
• 按类型进行文档审查技能——评估单份文档的内部质量；本技能则评估文档作为一个集合时彼此之间的关系。
• 本技能所践行的方法——需求可追溯性（RTM，正向／反向／双向）、单一事实来源／术语一致性、IEEE 830 一致性与完整性、敏捷 Definition of Ready（维度 6），以及变更影响分析（维度 7，修改的连带影响）——请参阅 references/sources.md。

渐进式披露

• references/coherence-bar.md — 八个维度各自的通过／缺口信号，以及跨文档发现项示例（尤其适用于维度 6／7／8）。
• references/sources.md — 八维度评估标准的研究来源。

正文预算

• description ≤ 1,024 个字符（agentskills.io 的上限；列表中合并计算的 description + when_to_use 会在 1,536 个字符处截断）。
• 正文 ≤ 约 500 行／5,000 个 token——每轮都会保留在上下文中；较重的内容放在 references/ 中。

更新日志

• 1.1.0（2026-06-15）— 面向生产环境的重新设计：评估标准从 6 个维度增至 8 个。维度 1–5 原样保留；深化维度 6（以 Definition of Ready 为骨干，并纳入对被引用但缺失的关键文档的发现）；新增维度 7（修改／差异范围内的重新审查——文档集层面的变更影响分析，涵盖 revise 后触发和上游变更触发两种情况；绿地项目中的文档集按比例将其视为不适用）；新增维度 8（版本偏差／过时的交叉引用，并增加过时维度重叠防护，避免与维度 1／3／4 重复标记；单一版本的文档集按比例将其视为不适用）；另加入明确的小型文档集比例性防护。此更新为增量式——输入与 VERDICT 输出契约保持不变。
• 1.0.0（2026-06-05）— 首个经过审查的版本（六维度跨文档评估标准）。