reviewing-technical-prose

审阅技术文稿

必备背景：technical-writing 技能，包括 references/style.md（禁用句式）和 references/truth.md（论断规则）。

概述

编辑是诊断。每处编辑都要指出所修正的具体缺陷；能修正缺陷的最小改动就是最佳改动。没有指出具体缺陷，却重写自然或已获认可的措辞，本身就是一种缺陷。

审阅完整文档，绝不只审阅其摘要。

何时调用，何时不调用

审阅或重写他人的技术文稿、为文档撰写问题报告，以及在交付自己撰写的内容前进行最终检查时，都应调用此技能。代码审查时不要调用（只审查代码中的文稿），也不要借审阅之机重议已定方案、扩大范围，或按自己的偏好重新调整文档风格。

严重程度对应关系

• BLOCKER：违反硬性规则（使用禁用的破折号、包含变更日志章节、在文稿中描述交付历史），以及引述来源不支持或找不到出处的任何论断。
• WARNING：使用禁用句式、存在结构缺陷（疑问式标题、结论埋得太深、段落可随意调换），以及仅有宽泛依据支持的论断。
• OBS：存在歧义、缺少润色，以及细心的作者很可能会注意到的任何问题。

重写他人的文稿

有一条要求高于所有规则：**内容必须保持一致。**按以下顺序操作：

1. 阅读原文。标出所有禁用句式和用词问题。

2. 写出一个版本，并大声读一遍。

3. 提出三个检查问题：

   • 哪个句子听起来仍像是语言模型写的？
   • 重写是否增添或删去了事实、数字、日期、姓名、来源或论断？
   • 重写是否以新的修辞形式重新呈现了已删除的模式？

   将重写后的段落当作原文重新检查。

4. 修复检查问题揭示的内容。增添和删减都算错误，即使这样能让文稿读起来更好。

绝不要为了补全句子而添加事实：应询问作者，或改用更简洁的句子。如果一个句子尝试两次后仍显生硬，就围绕段落的核心观点重写整个段落。只改动正文：代码块、frontmatter、表格数据和链接目标保持原样。

• **重写后仍使用原文的语言。**荷兰语文档应以荷兰语交付，同时始终遵守结构和真实性规则；若该语言有自己的专属词汇清单，则以该清单替代英语专属词汇检查。
• **作者可联系时，差异就是提案。**覆盖原文前，先展示重写内容。在仓库中无人值守时，提交记录就是提案，审阅起到相同作用。

当原文没有任何可还原的论断（背景介绍、释义、阐释含义的句子）时，正确的重写方式是删除这些内容，并在应当出现真实论断的位置标出缺口（**[input wanted: <the claim the sentence should make>]**；这是核心技能中 **[source wanted: ...]** 的论断级对应形式）。如果原文没有任何论断，那么重写结果中满是标记缺口正是预期结果，并非失败。

应保留的发现

禁用结构清单本身并不能证明任何问题；每种表达也会出现在优秀的人类写作中。只有同一段中出现多种迹象时才标记。

• 语法流畅，格式一致。
• 只有一种重复的句子开头：仅在重复没有增加任何内容时才修改。
• 用于强调的一句短句：只有连续出现一排残句才是问题。
• 一般的正式用词：清单列出了特定词语；并非每个正式用词都需要简化。
• 事实对比：“流水线设置标签，开发人员不设置”是陈述，不是对照修辞。
• 读者确实会认真权衡的选项：应保留在文档中。
• 用于限定范围的限定语：范围、假设以及安全或法律说明都应保留。只删去层层堆叠的部分。
• 迁移文档或发行说明中提及先前情况：此时变化本身就是主题。
• 被引用的词语：引用、标题或讨论该词的示例中，绝不改写。
• 有助于解释的比喻：只删去围绕比喻的修饰。
• 刻意的不自然表达：清晰的残句或不对称句式，不会仅仅因为可以润色就成为缺陷。

审查报告

• 第一行给出结论，发现按严重程度从高到低排列。
• 严重程度用语由使用它的报告定义：BLOCKER（无法继续）、WARNING（很可能需要返工；应修复，但不阻塞）、OBS（值得留意）。
• 每项发现都用一句话说明缺陷、位置（file:line、章节、任务 ID）、建议的修复方案和置信度。
• 明确写出无发现的情况（“FINDINGS: none”）。
• 文档中的说法若与代码矛盾，属于文档缺陷；报告时附上冲突来源。顺带发现的无关 Bug 不属于审查发现。
• 复审只列出尚未解决的问题。
• 肯定做得好的地方。

交付检查清单

任何文档发出前：

• 与同目录中的现有文档保持一致；如果存在 README.md 索引，则将其加入索引
• 不含 em dash、en dash 或 --；不含变更日志章节或“最后更新”字段；正文中不含工单键、阶段或 SHA
• 不含禁用结构（technical-writing 技能的 references/style.md）；至少检查摘要和结尾段落
• 标题说明内容：不使用疑问句，不使用“What X means”这类表述，标题不在首句中重复
• 先给结论：文档、章节和段落层面都先给出结论
• 操作步骤：每句话只描述一个操作，并明确执行者
• 提出或决定事项的部分：每项重要选择都说明理由，并记录一个有实际意义的替代方案，同时列出代价，而不只是好处
• 事实与提案可区分；估算值应标明；未知事项应明确说明
• 每项含数字的说法都能追溯到文档中注明的来源
• 核对引用：确认章节编号、相对链接和文件名实际存在
• 术语保持一致，并在首次出现时定义；一个概念只使用一个术语
• 朗读检查：至少朗读摘要；不出现一排残句，不出现三句以相同开头的句子
• 移除名称测试，检查开头和摘要：删除产品名称后，陌生读者仍能看出文本讨论的内容
• 检查冷读和整体连贯性：对从未看过相关对话或反馈轮次的读者也自然；全文语气一致，不露拼接痕迹，不解释文档为何以这种方式撰写
• 重写时：不得增删任何事实、数字、日期或来源