审查本次 OpenSpec 变更文档是否与前序讨论、当前代码现状和 OpenSpec 文档规范一致,识别遗漏、冲突和不合理假设,并给出可执行的补充建议,按以下流程执行。 ## 约束 - 仅修改本次变更文档,不修改源码 - 默认按 `spec-driven` workflow 审查;识别 change 后先确认 `schemaName`;若实际 schema 不同,说明差异,仅对实际存在的 artifacts 做审查 - 优先使用当前会话中的讨论和已生成的变更文档;仅在无法明确 change、`schemaName` 或文档范围时,再用提问工具或 OpenSpec 命令补充定位 - 每批文档修改建议执行前用提问工具获得用户确认 - 删除/重写前用提问工具获得用户确认,并先备份原文件为 `{file}.bak.{timestamp}` ## 1. 收集 并行读取: - 本次 change 的实际 artifacts;在 `spec-driven` 下通常包括 `proposal.md`、`design.md`、`tasks.md`、`specs/*.md` - 当前会话中与本次变更相关的讨论、澄清、边界约束、非目标、待确认事项 - 与本次变更直接相关的源码、测试、README、架构文档 - `openspec/config.yaml` - 现有 `openspec/specs/**/spec.md` 中与本次变更相关的规范,相关性来源包括:`proposal.md` 的 `Capabilities` / `Modified Capabilities`、讨论中提到的受影响能力、`design.md` / Impact 中提到的模块、相关代码对应的现有能力 若当前上下文无法明确 change 或文档路径: - 先用提问工具让用户确认 change 名称或文档范围 - 仍无法确认时,再执行 `openspec status --change "{name}" --json` 和 `openspec instructions apply --change "{name}" --json` 辅助定位 若已明确 change,但尚未确认 `schemaName`,先读取 change 元数据或执行 `openspec status --change "{name}" --json` 确认。 若缺少讨论记录,明确说明本次降级为"文档 + 代码现状审查",不做讨论一致性结论。 ## 2. 分析 按以下优先级检查: | 优先级 | 维度 | 检查点 | | ---- | ---- | ------ | | P0 | 讨论一致性 | 仅在存在讨论记录时检查:文档是否完整覆盖已确认的目标、范围、非目标、约束、边界条件、风险、决策点、待办事项;若无讨论记录,标记为"跳过" | | P1 | 代码现实性 | 文档对当前模块、接口、数据结构、命名、依赖、目录结构、复用路径的描述是否准确;是否把"计划变更"误写成"当前现状";是否遗漏真实受影响的现有能力 | | P2 | 文档内部一致性 | 对实际存在的 artifacts 检查是否互相支撑;在 `spec-driven` 下重点检查 `proposal.md`、`design.md`、`tasks.md`、`specs/*.md`;`Capabilities` / `Modified Capabilities` 是否完整;每个 capability 是否有对应 spec;`tasks.md` 是否覆盖 `design.md` 和 `specs/*.md` | | P3 | OpenSpec 合规性 | 对实际存在的 artifacts 检查是否遵循 OpenSpec 格式和术语;`specs/*.md` 是否只描述行为与约束、不混入实现细节;`tasks.md` 是否一行一个任务;是否混入 git 操作任务 | 分析时区分两类情况: - 文档对当前代码现状的描述错误 - 文档描述的是预期变更,本来就应当与当前代码不同 重点识别: - 讨论中已确定但文档未记录的内容 - 文档基于错误现状做出的设计或任务拆分 - 文档之间相互冲突的目标、方案、约束、任务 - `proposal -> specs -> design -> tasks` 链路中的断点 - `Modified Capabilities` 应更新但未更新的现有 spec 输出审查结果: 1. **问题总览表**:问题类型 × 涉及文档数 2. **讨论遗漏清单**:讨论已确定但文档未体现的内容;若缺少讨论记录,标记为"未审查" 3. **现实性问题清单**:与当前代码现状不符的描述、假设或影响分析 4. **文档冲突清单**:proposal、design、tasks、specs 之间的不一致 5. **OpenSpec 规范问题清单**:格式、术语、结构问题 6. **待澄清清单**:仅靠讨论和代码仍无法判断的事项 7. **逐项分析**:每个问题说明位置、问题、影响、建议 8. **补充建议方案**:按文件列出建议补充/修正的内容、原因和可选方案 若所有清单均为空,输出"审查通过,未发现问题",跳至步骤 5。 ## 3. 计划(用户确认) 先针对"待澄清清单"用提问工具逐项向用户确认。 再整理完整修复方案,按文件列出: - 建议修改的文件 - 需要补充或修正的内容 - 修改原因 - 若存在分支方案,分别说明适用前提 用提问工具展示完整修复方案,获得用户确认后执行。 ## 4. 执行 逐项修改已确认的变更文档,不修改源码。 若涉及删除或重写: - 先创建备份文件 `{file}.bak.{timestamp}` - 再执行修改 执行后重新读取所有被修改的文档,并复核: - "讨论遗漏清单" 是否已清空或已标注保留原因 - "现实性问题清单" 是否已清空或已标注为预期变更 - "文档冲突清单" 和 "OpenSpec 规范问题清单" 是否已清空 ## 5. 收尾 列出所有修改的文件、备份文件和变更摘要。 若本次因缺少讨论记录而降级执行,或有问题因信息不足暂未处理,单独说明。