openspec-shcema/code-drive/prompts/blocker-revise.md

blocker-revise

当 OpenSpec code-drive 的 apply 阶段生成 blocker.md 并暂停时，按照本提示词修订规划 artifacts。目标是修正不成立的部分，而不是强行继续实现。

输入

• 当前 OpenSpec change 目录
• blocker.md
• requirements.md
• design.md
• plan.md
• tasks.md
• openspec/schemas/code-drive/schema.yaml（用于读取各 artifact 的 instruction）

工作流

1. 阅读并理解阻塞

阅读 blocker.md，识别：

• 阻塞点的本质（不是症状）
• 当前位置：任务编号、plan.md 阶段、相关文件
• 已尝试的方案及失败原因（避免重复）
• blocker.md 建议的修订目标

2. 影响分析

根据 blocker.md 的影响范围，系统分析上下游影响链：

• 如果 requirements.md 需要修订：检查 design.md 的哪些决策依赖它，再检查 plan.md 的哪些阶段受影响，最后检查 tasks.md 的哪些 checkbox 需要取消
• 如果 design.md 需要修订：检查 plan.md 的哪些阶段依赖它，再检查 tasks.md 的哪些 checkbox 需要取消
• 如果 plan.md 需要修订：检查 tasks.md 的哪些 checkbox 依赖它，以及是否有下游阶段依赖被阻塞阶段的输出
• 如果 tasks.md 需要修订：只影响当前任务及其直接依赖

记录每个 artifact 的影响程度：必须修订 / 可能受影响 / 无影响。

3. 确定修订入口

根据影响分析，确定需要修订的最上游 artifact：

• 如果需要修订 requirements.md：从 requirements 开始，依次修订 design、plan、tasks
• 如果需要修订 design.md：从 design 开始，依次修订 plan、tasks
• 如果需要修订 plan.md：从 plan 开始，修订 tasks
• 如果只需要修订 tasks.md：只修订 tasks

4. 用户决策

让用户从 blocker.md 中列出的可选方案中选择。如果选项不足，提出 2-3 个方案并说明取舍。工具支持时优先使用 question/choice 工具。

5. 执行修订

从修订入口开始，按正常 code-drive 流程逐层修订下游 artifacts。

每个 artifact 的修订必须遵循该 artifact 的 instruction 和 template：

1. 读取 schema.yaml 中该 artifact 的 instruction
2. 读取该 artifact 的 template
3. 按 instruction 的工作规则和必需章节进行修订
4. 确保修订后的 artifact 符合 template 结构

修订范围原则：

• 只改错误的部分，不重写整个章节（除非整个章节的基础假设不成立）
• 改了 plan.md 阶段的实现步骤时，同步更新 tasks.md 对应 checkbox 的描述
• 改了 design.md 的关键决策时，检查 plan.md 的代码模式是否需要同步，但不自动重写
• 改了 requirements.md 时，逐层向下检查影响，每层只改受影响的部分
• 如果修订导致 tasks.md 分组结构变化，重新对齐 plan -> tasks 映射

保留已完成任务：

• 已完成且不受阻塞影响的 tasks：保留 checkbox
• 已完成但被阻塞证明无效的 tasks：取消 checkbox，并在修订记录中说明原因
• 未完成的 tasks：根据修订结果更新描述或删除
• 如果阶段需要拆分：在 plan.md 中新增阶段，将已完成部分和待完成部分分开

6. 修订后验证

每个被修订的 artifact 完成后，执行以下一致性检查：

Instruction 合规性：

• 每个被修订的 artifact 是否符合其 instruction 中的工作规则
• 每个被修订的 artifact 是否包含其 instruction 中要求的必需章节
• 每个被修订的 artifact 是否符合其 template 结构

上下游一致性：

• 需求覆盖：requirements.md 的每条需求是否仍有 design.md 决策覆盖
• 决策落地：design.md 的每个关键决策是否在 plan.md 中有实现路径
• 阶段覆盖：plan.md 的每个阶段是否在 tasks.md 中有对应分组
• 任务可追溯：tasks.md 的每个 checkbox 是否能回溯到 plan.md 的某个阶段
• 验证闭环：design.md 的“验证方向”是否在 plan.md 的“验证策略”中有体现

7. 处理 blocker.md

在 blocker.md 末尾追加“修订记录”：

## 修订记录

- 选择方案：
- 选择理由：
- 修改的 artifacts：
  - `xxx.md`：具体变更描述
  - `xxx.md`：具体变更描述
- 被取消勾选的 tasks：
  - X.Y：取消原因

按项目约定保留或归档 blocker.md（建议保留作为审计线索）。

8. 完成

告诉用户重新运行 /opsx:apply <change-name>；apply 应跳过已完成 checkbox 并从修订后的待办任务继续。

规则

• 除非用户明确要求，不要在使用本提示词时实现代码；本提示词只负责修订规划 artifacts。
• 不要默认重写全部 artifacts，只修订解决阻塞所需的最小上游点及其下游影响。
• 不要未经用户确认新增需求、依赖、架构方向或范围。
• 不要取消已完成任务的勾选，除非阻塞证明该已完成工作不正确。
• 每个被修订的 artifact 必须遵循其 instruction 和 template，即使只是局部修订。
• 如果工具支持，使用 todo/plan 工具跟踪修订流程，但最终事实必须写回 artifacts。

完成检查

• blocker.md 已追加修订记录，并被保留或归档。
• 选定的修订方向已记录在受影响 artifact 中。
• 每个被修订的 artifact 符合其 instruction 的工作规则和必需章节。
• 下游 artifacts 与修订后的上游内容一致。
• 已完成任务的 checkbox 被保留，除非明确失效。
• 用户知道需要重新运行 apply 继续实现。