feat: 初始提交

docs/prompts/prompt-proposal-review.md

@@ -0,0 +1,139 @@
+审查本次 OpenSpec 变更文档是否与前序讨论、当前实际状态和实际 OpenSpec workflow 一致，重点检查 `fast-drive` workflow 下的 `design.md` 是否足以在上下文压缩或新会话中指导后续 `apply`，并识别遗漏、冲突和不合理假设，给出可执行的补充建议，按以下流程执行。
+
+## 约束
+
+- 仅修改本次变更文档，不修改实际产物
+- 默认按 `fast-drive` workflow 审查；识别 change 后先确认 `schemaName`；若实际 schema 不同，说明差异，仅对实际存在的 artifacts 做审查
+- 在 `fast-drive` workflow 下，核心 artifacts 是 `design.md` 和 `tasks.md`；不要要求存在 `proposal.md` 或 `specs/*.md`
+- 在 `fast-drive` workflow 下，`design.md` 是 scope、requirements、decisions、guardrails、execution direction 和 verification expectations 的 source of truth，`tasks.md` 必须从 `design.md` 派生
+- 优先使用当前会话中的讨论、explore/propose 阶段结论和已生成的变更文档；仅在无法明确 change、`schemaName` 或文档范围时，再用提问工具或 OpenSpec 命令补充定位
+- 每批文档修改建议执行前用提问工具获得用户确认
+- 删除/重写前用提问工具获得用户确认，并先备份原文件为 `{file}.bak.{timestamp}`
+
+## 1. 收集
+
+读取约束：
+
+- 直接使用 Read 工具并行读取文件，禁止使用 subagent/Task 工具做文件读取和内容转发
+- 不原样输出文件内容，仅在步骤 2 输出审查结论
+
+分步收集：
+
+a) 先并行读取核心入口和配置，确定范围：
+
+- 本次 change 的 `design.md`
+- 本次 change 的 `tasks.md`
+- workflow context/configuration，例如存在时读取 `openspec/config.yaml`
+- 若可定位到 schema，读取对应 schema；`fast-drive` 下优先读取 `openspec/schemas/fast-drive/schema.yaml`
+
+b) 从 `design.md` 提取审查基准：
+
+- `Context`
+- `Discussion Notes`
+- `Requirements`
+- `Goals / Non-Goals`
+- `Execution Guardrails`
+- `Affected Areas`
+- `Decisions`
+- `Execution Plan`
+- `Verification Plan`
+- `Risks / Trade-offs`
+- `Open Questions`
+
+c) 基于 `Affected Areas`、`Execution Plan`、`Verification Plan`、讨论中提到的受影响范围，并行读取相关实际产物、参考材料、验证材料、流程说明、配置、文档或沟通材料，确认文档是否贴合当前实际状态。
+
+d) 若实际 schema 不是 `fast-drive`，只读取实际存在的 artifacts；若存在 `proposal.md`、`specs/*.md`，再按该 schema 的要求补充读取和审查。
+
+若当前上下文无法明确 change 或文档路径：
+
+- 先用提问工具让用户确认 change 名称或文档范围
+- 仍无法确认时，再执行 `openspec status --change "{name}" --json` 和 `openspec instructions apply --change "{name}" --json` 辅助定位
+
+若已明确 change，但尚未确认 `schemaName`，先读取 change 元数据或执行 `openspec status --change "{name}" --json` 确认。
+
+若缺少讨论记录，明确说明本次降级为“文档 + 当前实际状态审查”，不做讨论一致性结论。
+
+## 2. 分析
+
+按以下优先级检查：
+
+| 优先级 | 维度                 | 检查点                                                                                                                                                                                                                                                                            |
+| ------ | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| P0     | 讨论承接性           | 仅在存在讨论记录时检查：`design.md` 是否完整记录已确认的目标、非目标、用户偏好、约束、边界条件、风险、关键决策、被否决方案和待澄清事项；若无讨论记录，标记为“跳过”                                                                                                                |
+| P1     | `design.md` 自包含性 | `design.md` 是否足以让看不到前序对话的执行者继续工作；是否包含完整 required sections；`Open Questions` 是否明确区分 blocking / non-blocking 或写出 `None`；是否存在依赖未记录聊天上下文的隐含要求                                                                                 |
+| P2     | 当前状态真实性       | `design.md` 对当前实际产物、流程、接口、内容、数据、配置、依赖、责任边界、参考材料和验证入口的描述是否准确；是否把“计划变更”误写成“当前现状”；`Affected Areas` 是否遗漏真实受影响区域                                                                                             |
+| P3     | `tasks.md` 派生性    | `tasks.md` 是否从 `design.md` 派生；是否覆盖 requirements、guardrails、decisions、execution plan 和 verification plan；是否依赖 `proposal.md` 或 `specs/*.md` 中未写入 `design.md` 的内容                                                                                         |
+| P4     | OpenSpec 合规性      | 对实际存在的 artifacts 检查是否遵循对应 schema 和 OpenSpec 术语；`tasks.md` 是否一行一个 `- [ ]` checkbox 任务、按 `##` numbered headings 分组、无无关的仓库/版本控制/发布操作任务；`design.md` 是否避免 task checkbox；最终 artifacts 是否仍保留模板注释、空表格行或占位任务文本 |
+
+分析时区分两类情况：
+
+- 文档对当前实际状态的描述错误
+- 文档描述的是预期变更，本来就应当与当前状态不同
+
+重点识别：
+
+- 讨论中已确定但 `design.md` 未记录的内容
+- `design.md` 中缺失或含糊的 requirements、acceptance criteria、guardrails、decisions、verification expectations
+- `Open Questions` 未明确区分 blocking / non-blocking、与 `tasks.md` 冲突，或包含 apply 前必须解决的 blocker
+- `tasks.md` 未覆盖 `design.md` 的要求、约束、执行计划、验证计划或文档/沟通更新要求
+- `tasks.md` 标记了无法验证、跨行、过大、顺序错误或包含无关仓库/版本控制/发布操作的任务
+- 文档仍保留 `<!-- ... -->` 模板注释、空表格行、`Replace with...`、`TBD`、`TODO` 等未解决占位内容
+- 文档基于错误当前状态做出的设计或任务拆分
+- 文档之间相互冲突的目标、方案、约束、任务和验证要求
+- `fast-drive` change 中仍错误依赖 `proposal.md`、`specs/*.md`、`Capabilities` 或 `Modified Capabilities` 的内容
+
+输出审查结果：
+
+1. **问题总览表**：问题类型 × 涉及文档数
+2. **讨论遗漏清单**：讨论已确定但 `design.md` 未体现的内容；若缺少讨论记录，标记为“未审查”
+3. **Design 自包含性问题清单**：缺失、含糊或无法指导新会话 apply 的内容
+4. **当前状态问题清单**：与当前实际状态不符的描述、假设或影响分析
+5. **Tasks 派生与覆盖问题清单**：`tasks.md` 未从 `design.md` 正确派生或覆盖不足的内容
+6. **文档冲突清单**：`design.md`、`tasks.md` 和实际存在的其他 artifacts 之间的不一致
+7. **OpenSpec 规范问题清单**：格式、术语、结构问题
+8. **待澄清清单**：仅靠讨论和当前状态仍无法判断的事项
+9. **逐项分析**：每个问题说明位置、问题、影响、建议
+10. **补充建议方案**：按文件列出建议补充/修正的内容、原因和可选方案
+
+若所有清单均为空，输出“审查通过，未发现问题”，跳至步骤 5。
+
+## 3. 计划（用户确认）
+
+先针对“待澄清清单”用提问工具逐项向用户确认。
+
+再整理完整修复方案，按文件列出：
+
+- 建议修改的文件
+- 需要补充或修正的内容
+- 修改原因
+- 若存在分支方案，分别说明适用前提
+
+用提问工具展示完整修复方案，获得用户确认后执行。
+
+## 4. 执行
+
+逐项修改已确认的变更文档，不修改实际产物。
+
+在 `fast-drive` workflow 下，通常只修改本次 change 的 `design.md` 和 `tasks.md`；若实际 schema 存在其他 artifacts，仅在确有必要且用户确认后修改实际存在的 artifacts。
+
+若涉及删除或重写：
+
+- 先创建备份文件 `{file}.bak.{timestamp}`
+- 再执行修改
+
+执行后重新读取所有被修改的文档，并复核：
+
+- “讨论遗漏清单” 是否已清空或已标注保留原因
+- “Design 自包含性问题清单” 是否已清空
+- “当前状态问题清单” 是否已清空或已标注为预期变更
+- “Tasks 派生与覆盖问题清单” 是否已清空
+- “文档冲突清单” 是否已清空
+- “OpenSpec 规范问题清单” 是否已清空
+- “待澄清清单” 是否已清空或已记录用户决策
+- 所有模板注释、空表格行和占位文本是否已清空或替换为有效内容
+
+## 5. 收尾
+
+列出所有修改的文件、备份文件和变更摘要。
+
+若本次因缺少讨论记录而降级执行，或有问题因信息不足暂未处理，单独说明。