resolve-beagle

Resolve：补齐规格缺口

获取由 brainstorm-beagle 生成的规格，通过研究、提出答案并直接改写规格，补齐其中尚存的缺口——包括明确列出的待解问题，以及自我审查时遗漏的潜在问题。

最终状态应为：规格中没有已知的待解问题，也没有占位需求。之后即可立即开始规划。

<hard_gate> 此技能不会编写代码、搭建项目脚手架、设计架构或制定实施计划。它只编辑规格文档。“回答待解问题”是指提出关于做什么／为什么的答案，并给出理由——绝不涉及如何实现。如果某个问题需要实施设计，应附注说明并暂缓处理。 </hard_gate>

门槛（通过后方可进入下一步）

以下为客观的通过条件，不能只凭口头断言跳过步骤：

1. 已定位规格 — 已知目标文件路径，且 Read 成功（或者用户在你列出 3–5 个最近修改的 docs/specs/ 候选文件后，提供了有效路径）。
2. 已公布缺口列表 — 在一条消息中列出所有明确的待解问题条目，以及你将纳入处理范围的每个潜在缺口。在用户调整列表（添加／删除／暂缓）或明确指示你按该列表继续之前，不得开始调度研究。
3. 每个缺口都有研究记录 — 提出缺口 G 的方案前，必须先为 G 准备一份结构化记录：建议答案、1–2 个被否决的替代方案及其理由，以及证据（文件:行号、URL 或规格内引用）。没有记录就不能提出方案。
4. 单一方案队列 — 当前缺口尚无明确结论（已接受、已应用修订后的措辞、已否决并说明后续处理，或说明理由后暂缓）时，不得开始讨论下一个缺口的方案。
5. 改写后核对一致性 — 编辑后，通读一次完整规格并解决各部分之间的矛盾；随后按照 ../brainstorm-beagle/references/spec-reviewer.md 中的自我审查清单进行检查，并在本轮修复所有未通过项，除非用户选择后续再审。
6. 提交 — 除非用户在 § 提交中对提交提示回答“是”，否则不得执行 git commit。

工作流程

1. 定位规格 — 使用用户明确提供的路径，或 docs/specs/ 中最近修改的文件
2. 提取缺口 — 解析待解问题，并审查潜在问题（占位内容、含糊需求、缺少理由、矛盾）
3. 展示缺口列表 — 在一份摘要中列出所有计划补齐的内容，让用户在开始研究前添加或移除项目
4. 分派研究 — 每个缺口安排一项任务；条件允许时通过子 Agent 并行处理，否则在当前流程中依次处理
5. 提出答案 — 一次提出一个方案，并附上建议、替代方案和证据
6. 直接改写规格 — 将已解决的项目移至相应章节；不得悄然遗漏任何内容
7. 自我审查 — 使用 brainstorm-beagle 所用的同一份清单（参见 ../brainstorm-beagle/references/spec-reviewer.md）
8. 询问是否提交 — 询问用户是否提交更改；未经询问不得提交

Locate spec → Extract gaps → Show list ──→ User adds/removes
                                          → Dispatch research (parallel if possible)
                                          → Propose answers (one at a time)
                                                → User decision → next
                                          → Rewrite spec in place
                                          → Self-review (fix inline)
                                          → Ask about committing

定位规格

如果用户提供了路径，请使用该路径。

否则，列出 docs/specs/ 中最近修改的 3–5 个文件，并询问：“要处理 <most recent>，还是其他文件？”不要扫描整个目录树——按照 brainstorm-beagle 的约定，规格文件位于顶层。

如果不存在规格目录，请向用户索要路径。

提取缺口

两类问题都算作缺口：

明确缺口 — 规范中 Open Questions 标题下的每个项目符号都是一项研究任务。

潜在缺口 — 在头脑风暴的自我审查中被遗漏的问题。扫描规范，查找：

问题	表现形式
占位符	TBD、TODO、“待定”、用省略号充当内容
含糊的要求	“快速”“简单”“良好”“用户友好”“直观”——没有可供验证的标准
缺少理由	限制或范围外事项没有说明“为什么”
矛盾	要求与另一项要求、限制或范围外事项冲突
成功标准不可测试	没有可观察的方式来验证要求是否达成
实现细节泄漏	要求规定了如何实现，而不是要实现什么
未被使用的接口	必须实现的事项引入了新的对外接口（API 接口、命令、端点、导出契约），但规范中的其他内容都未使用它
组合关系未明确	同一数据管道中已有机制位于上游或下游，会转换（截断、筛选、缓冲、重排、去重）该功能依赖的数据，但没有分析它与该功能的组合方式

将潜在缺口视为首要事项的原因是：规范写着“快速”或“良好的 UX”，并不会因为没人明确指出问题就算是得到了回答。规划阶段还是会被这些词绊住。现在就把它们解决掉。

分派研究任务之前，先在一条消息中向用户展示合并后的列表——“以下是我计划解决的问题”——并让他们添加、移除或暂缓处理条目。不要逐项征求许可；这就是提案步骤。

分派研究任务

每个缺口恰好对应一项研究任务。先对每项任务分类——任务类型决定研究需要使用哪些工具：

任务类型	示例	工具
代码库模式	“现有的 --start-at 模式如何运作？”“SKILL_MAP 在哪里定义？”	搜索代码库（grep/glob/read）
外部信息 / API	“该 Agent 的 SDK 提供了哪些生成子 Agent 的功能？”“Codex 有钩子吗？”	网络搜索和页面抓取（如果可以联网）
设计权衡	“合并后的报告应采用什么格式？”“去重应如何处理？”	推理 + 规范中已有的类似参考点
范围 / 策略	“配置/文档文件应路由到某个技术栈，还是使用回退方案？”	结合规范自身的 Core Value 和 Constraints 进行推理

使用子 Agent（首选）

如果 Agent 支持子 Agent，则将每项研究任务作为独立子 Agent 分派——在同一轮中全部分派，以便并行执行。每个子 Agent 都有自己的上下文窗口，这很重要：缺口往往附带大量支撑上下文（规范、代码库），你不会希望把这些内容全塞进同一段对话。

参见 references/subagent-prompts.md 中的提示词模板（每种任务类型各一份）。

研究结果必须采用结构化格式：推荐答案、1–2 个备选方案及其被否决的原因，以及具体证据（文件:行号引用、URL 或规范现有章节的引用）。每项结果控制在约 300 词以内——你需要的是决策，而不是对话记录。

不使用子 Agent

如果没有可用的子 Agent 工具，就亲自逐项研究。按成本由低到高的顺序进行：代码库问题，然后是外部信息，再然后是设计权衡，最后是范围/策略。为每项问题给出相同结构的提案。这样速度较慢，但不会留下未解决的缺口。

提出答案建议

一次只提出一项建议。每项建议包括：

• 差距——用一行重述
• 建议答案——给出你的最佳判断，并说明原因
• 替代方案——列出 1–2 个可信选项，并说明为何不采用
• 证据——文件:行号引用、URL，或对规范中已有决策的引用

用户可以接受、修改或拒绝。如果用户想讨论，就沿着这个话题继续；确定后再继续下一项。

顺序很重要。 按以下大致顺序解决：

1. 首先处理代码库实际情况方面的差距（这些差距可能会影响设计取舍）
2. 其次处理策略/范围方面的差距（这些差距会影响下游的所有内容）
3. 最后处理格式/呈现方面的差距（这些差距取决于前述内容）

如果某项差距只有用户掌握的信息才能解决（预算、利益相关方偏好、未说明的限制），不要猜测——直接提问。这样比提出错误建议后再推翻更省事。

重写规范

随着决策逐步确定，将其迁移到相应位置：

差距类型	确定后的去向
架构或策略决策	在 关键决策 下新增条目（并列出考虑过的替代方案）
具体行为	在 需求 下新增条目（标注为必须/应该/不在范围内）
硬性限制	在 约束 下新增条目（并说明理由）
研究中发现的外部参考资料	在 参考资料 下新增条目
被替换的模糊需求	直接改写现有需求；不要重复添加
有意推迟处理的事项	保留在 待解决问题 中，并添加 deferred: <reason> 后缀

两条重要规则：

• 绝不要悄无声息地删除待解决问题。 要么解决，要么说明理由后迁移，要么明确推迟并说明原因。删除问题却不留记录，会导致规范在不同会话间倒退。
• 重写整份规范，而不只是修改涉及的章节。 变更会相互影响：新的关键决策可能与旧需求矛盾，已解决的待解决问题也可能使某项约束失效。编辑后从头到尾通读规范并协调一致。

自我审查

运行 ../brainstorm-beagle/references/spec-reviewer.md 中的检查：

• 没有占位符
• 没有矛盾
• 没有实现细节泄漏
• 所有需求均可测试
• 约束和范围外事项均有理由
• 不得新增没有明确使用者的对外接口（API 接口、命令、端点、导出契约）——要么注明使用者，要么移至未来考虑
• 记录任何会转换该功能数据的现有上游/下游流水线机制，并将其作为标记为 needs-spike-before-planning 的关键决策；不得置之不理

将发现的任何问题直接修复后，再交还用户。如果重写期间出现新的差距（有时确实会），将其添加到“发现的新差距”列表，并询问用户是现在解决还是留待后续处理。

提交

重写后，进行总结并询问：

"规范已更新。已解决 N 个明确问题和 M 个潜在差距。要我将其提交为 docs: resolve open questions in <topic> spec 吗？"

如果用户同意，就提交。如果不同意，就将工作树留给用户。不要未经询问就提交——用户可能想先检查差异，或将其与其他更改一起提交。

核心原则

• 闭合问题。 目标是确保规格中没有任何会阻碍规划的未解问题。半解决比明确延期更糟。
• 每个缺口对应一项研究任务。 不要把任务混在一起——这会让提案步骤更难审核，也会削弱证据链。
• 重证据，不重观点。 每项提案都要引用依据——文件、URL 或现有的规格决策。“我认为”还不够。
• 仍然只回答是什么，而不是怎么做。 答案应作为决策写入规格，而不是实施设计。如果回答需要考虑实施方式，就延期处理。
• 如实延期。 暂时无力解答的问题应保留为待解决问题，并用一句话说明原因。承认已知缺口，总比粉饰太平好。
• 尽可能并行处理。 子 Agent 在隔离环境中运行——尽可能积极地拆分任务。顺序研究应是备用方案，而不是默认做法。
• 避免不必要的打断。 缺口列表只展示一次，之后只有需要人工判断的决策才询问用户。