hrt-adversarial-authoring

hrt-adversarial-authoring

跨上下文对抗式编写：一个子 Agent 起草，另外两个子 Agent 分别从两个正交角度质疑草稿，然后才予以接受。这两个子 Agent 都不了解作者的推理过程，只能看到提供给它们的输入。

此技能由两个调用方共用。调用指令 MUST 说明正在编写哪种产物——这一选择将决定草稿内容、两份审查清单，以及下文的解决目标。除此之外，两种调用方的流程完全相同。

参数（由调用方设置）

• artifact：specs 或 design。（此处不审查 proposal：其依据是用户自己的访谈回答，并由 hrt-artifact-lint 和用户阅读确认来检查。）
• content_sections：草稿子 Agent 必须编写的章节。
  • specs：proposal 的 Capabilities 章节中列出的每项能力各编写一个规格文件——按照 specs 阶段的格式规则，编写包含 WHEN/THEN 内容的 ### Requirement 块和 #### Scenario。
  • design：按照 design 阶段的格式规则，编写 Context、Goals/Non-Goals、Decisions、Shape / Seams（当变更新增可调用代码时）、Risks/Trade-offs、Migration Plan、Open Questions。
• grounding_inputs：草稿子 Agent 可以读取的产物。
  • specs：proposal.md、openspec/specs/ 中现有的规格文件（用于确定能力名称）。
  • design：proposal.md、specs/**/*.md。

流程

1. 起草。 使用给定 artifact 对应的 grounding_inputs 和 content_sections 启动一个子 Agent。它只负责起草——不进行自我审查，不使用模棱两可的占位内容。写作时，文案 MUST 遵循 plain-language-writing 技能的 ARTIFACT 规则，而不是事后再套用这些规则。输出格式：先输出 ## Draft（产物内容），再输出 ## Author Notes（作者写作时标记的未决问题或假设）。

2. Lint。 编排会话运行 hrt-artifact-lint 技能，并直接修复每个 ERROR（确定性问题，每项只有一种正确修复方式），让审查者无需关注 grep/count 结构。WARN 行作为背景信息提供给审查者。

3. 审查——两个子 Agent 使用两个正交视角，并发启动；彼此看不到对方的输出，也看不到 Author Notes。 两者都获得 lint 后的草稿，以及作者使用的同一组 grounding_inputs，但看不到作者除 ## Author Notes 之外的推理。各司其职——Critic 负责内容、逻辑和决策质量；Auditor 负责结构判断；lint 负责计数和格式。不要重复审查或越权。

   精简设计捷径（仅适用于 artifact: design）。 如果 lint 后草稿的 Shape / Seams 正文恰好是 “no new code surface”，且 Decisions 至多只有一项，且没有关于被否决方案的推理，则只运行 Destructive Critic，跳过 Structural Auditor。这么精简的 design.md 无需 Auditor 进行判断检查。此时，每条 Critic 发现都会呈现给用户（agreement 自动解决路径需要两位审查者），在这种规模下是安全的。此规则不适用于 specs。 后果门槛（两位评审者均适用）。 只有明确指出读者或实现者在问题未修复时会具体遇到什么（误读某项主张、构建受阻、被迫返工、需求未经测试），才将发现列入 ## Required Changes。未指出此类后果的批评——“前提薄弱”“读起来别扭”——应列入 ## Suggested Improvements（不阻塞，不逐项提问）。

   • 破坏性评审者（内容与逻辑，检查清单取决于 artifact）。每项发现都要指出一个具体事实：如果该事实属实，就会推翻这项发现；没有这样的事实，发现就尚未准备好报告。
     • specs：每项主张是否都能追溯到 proposal.md？有没有输入依据不支持的断言？范围是否超出提案？假设作者过度自信——找出缺失或错误之处，而非验证内容。前提已在 proposal.md 中定案——不要重新讨论；真正的前提错误应列入 ## Risks and Open Questions，而非 Required Change。
     • design：这是对决策质量的评审，而非可追溯性检查——Decision 的对错取决于其推理是否成立，而非是否符合某份源文档。前提、问题和目标已在上游定案——不要重新争论；真正的前提错误只列入一次 ## Risks and Open Questions。逐项检查 Decision：是否有合理的替代方案被无正当理由地否决？逐项检查 Risk/Trade-off：缓解措施是否足够，是否遗漏了合理的故障模式（事前验尸：假设它在生产环境中失败，倒推原因）？逐项检查 seam：这是正确的测试边界吗？它会让测试依赖实现细节吗？现有的更高层边界是否已覆盖它？对于会创建新模块或 seam 的 Decision，指出作者未考虑的一种结构上不同的方案，并说明它是否处于劣势；如果某项决策没有这样的替代方案，则无需提出发现。
   • 结构审计员（处理 linter 无法判断的结构性问题；不会重新检查井号数量、复选框格式、章节是否存在或 Covers: 是否存在，这些由第 2 步的 lint 负责）。先假设存在缺口，直到检查确认——完全没有发现的情况应该很少。审计员在此提出的每项发现都是 UNANCHORED（依据的是对意图的解读）：
     • specs：每项需求是否都真正可测试——是否包含可衡量的动词、单位或条件，而非仅仅存在且缺乏实际意义？每个 #### Scenario 是否都真正描述 WHEN/THEN 行为，而不是伪装成场景的实现细节？MODIFIED requirement 是否包含完整的更新内容，还是遗漏了细节？
     • design：空白或 N/A 的 Migration Plan 是否确实不适用，还是掩盖了实际的部署／回滚步骤？每项 Decision 对备选方案的论证是否真正有理有据，还是只占位？标注“no new code surface”的跳过行是否确实不涉及代码？每个 seam 签名是否描述了真实边界，还是凭空捏造？Seam 遵循 mattpocock 的 to-spec 规则：测试应连接到可用的最高层入口，且 seam 越少越好（理想情况下为一个）。指出测试内部协作者的 seam，以及多个本可由一个更高层 seam 覆盖的 seam。
   • 每位评审者的输出格式：## Review Summary、## Required Changes（每项标注为 ANCHORED 并附上其 grep／计数，或标注为 UNANCHORED——审计员的发现全部为 UNANCHORED；每项都须通过后果门槛）、## Suggested Improvements（不阻塞：可选的改进，以及未通过后果门槛的真实发现）、## Risks and Open Questions。

4. 解决。 协调会话合并两位评审者的 Required Changes（仅对位置和问题都相同的发现去重；绝不通过 LLM 判断来裁决评审者之间的分歧）。对每项合并后的发现进行分类：

   • 自动解决（直接修复，不提示用户），满足以下任一条件即可：(a) ANCHORED——修复前自行重新运行 grep／计数以确认；(b) 两位评审者独立提出了相同的发现（真正重复）——两个独立视角意见一致，可以替代单个评审者自行声明“这样做安全”。记录所做的更改。
   • 需要用户单独答复——其他所有发现中，凡是 (i) 会改变 proposal.md 已定下的范围，(ii) 属于单向变更（数据迁移或破坏性架构变更、删除存储的数据、变更已发布的 API 或事件契约、移除其他代码正在读取的配置或标志，或需要手动撤销的步骤），或 (iii) 属于高严重性的安全性权衡。将所有此类发现放在同一条消息中。每项先中性地说明权衡，再给出你的建议，以便用户先权衡利弊，再看到你的答案。用户必须逐项回答；单独回复“ok”并不涵盖这些事项。只应用用户确认或调整后的内容。
   • 汇总确认——其他所有内容（所有仅由一位评审者提出的其他 UNANCHORED 发现，以及 Suggested Improvements、Risks and Open Questions 和 Author Notes）。在需要用户单独答复的发现解决后，用一条消息列出；每项都要给出建议的解决方案和一句理由。回复“ok”即表示全部接受；用户也可以指出任何例外。最多展示 5 条 Suggested Improvements，按重要性从高到低排列，并说明还省略了多少条。只有一位评审者提出的 UNANCHORED 发现绝不自动解决，无论看起来多么容易处理：都要留在汇总中等待用户回复“ok”。
   • 两条消息都必须遵循 plain-language-writing 技能的 COMMS 规则。
   • “暂缓处理”／“接受偏差”并非真正的替代方案——如果一项发现除了修复之外只有这些选项，就不应交由用户决策。即使已经有明确的修复方案，只要合格的作者仍可能选择其他补救方式，该发现就不能自动解决。
   • 对于 design，继续保持现有倾向：相较于 specs，更多情况下应让用户做决定，即使是接近范围问题的 ANCHORED 发现也如此（此类发现需要用户单独答复）——决策质量判断的可靠性明显低于 lint 的确定性检查。破坏性评审者对 seam 边界质量的检查属于 UNANCHORED，应列入汇总；如果它会改变测试已经依赖的 seam，则应交由用户单独答复。

5. 定稿。 Required Changes 解决后，基于（可能已调整的）草稿，使用当前阶段的模板编写文档。 如果存在 dark.md，调用方会在第 4 步将 hrt-dark-mode-routing 技能应用于任何原本会呈现给用户的发现。

后备方案

如果无法启动子代理，请说明无法完成对抗式编写，并询问用户是否要继续采用单次编写。不要悄悄跳过审查步骤。如果无法运行 hrt-artifact-lint，则由结构审计员手动执行其检查——请说明这一点，不要跳过检查。