Alfred/openspec/schemas/code-drive/prompts/blocker-revise.md

blocker-revise

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

目标

读取 blocker.md 及上下游 artifacts，识别阻塞本质，定位最上游的修订入口，通过用户决策流程选定修订方向，按 code-drive 各 artifact 的 instruction 逐层修订受影响的部分，最终让 apply 可以从修订后的待办任务继续。

本提示词是 code-drive 中除 requirements 之外唯一允许向用户发起决策型提问的入口，决策能力受"用户决策流程（强制协议）"约束。

输入

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

工具使用（先决说明）

• todo 工具：用于跟踪步骤 5/6/7 内的子步骤进度；子步骤颗粒度（如 5.1 / 5.2 / 5.3）直接对应 todo 条目；todo 只是过程跟踪，最终事实必须写回对应 artifact 文件
• question / choice 工具：触发用户决策流程时必须优先使用（如工具支持），按"用户决策格式（强制）"组织候选与说明
• 读写工具：本提示词需要写入多个 artifact，但写入前必须先读取对应 artifact 的当前内容；禁止凭印象重写
• 只读探索工具：用于步骤 2 的代码库调查（仅在阻塞点涉及未被探索过的代码时使用）

用户决策流程（强制协议）

本协议是 blocker-revise 阶段的唯一决策出口。任何超出"修订执行细节"层级的方向选择必须走本协议，不得 AI 自决。

触发条件（命中即必须启动）

1. 核心修订方向存在多种可行路径：blocker.md 列出的可选方案 ≥ 2 个，或 AI 补充的方案与原方案构成真正的取舍（不是同一思路的两种写法）
2. blocker.md 建议的修订方向会扩展本次业务范围或引入核心新依赖：与原 requirements / design 不一致，必须显式征得用户同意
3. 修订入口在不同 artifact 之间犹豫：例如 blocker 表面指向 plan，但根因可能在 design 或 requirements，需要用户判断修订起点
4. blocker.md 未列出可选方案，仅描述了阻塞现象：AI 必须主动补充 2-3 个候选方向并请用户选择

未命中以上任何条件时，不得主动发起决策型提问；AI 自决范围参见下文。

AI 自决范围（无需启动用户决策流程）

以下类型的修订属于执行细节，AI 自决后直接执行，无需启动用户决策流程：

1. 执行步骤的局部调整：plan.md 阶段内步骤的拆分、合并、重排
2. 任务粒度细化或合并：tasks.md checkbox 的拆分/合并，但不删除整个分组
3. 描述措辞修正：澄清歧义、补充缺失细节、修正笔误
4. 已完成任务的保留决策：阻塞未证明无效时，已完成 checkbox 必须保留
5. 修订记录的措辞与格式：blocker.md 末尾的修订记录按本提示词模板填写
6. 工具使用顺序：todo / 读写工具的使用顺序与时机

用户决策格式（强制）

每次启动用户决策流程时，输出必须包含：

1. 2-3 个候选选项：每个选项含义明确，避免"方案 A / 方案 B"这类无信息标签
2. 推荐方案：AI 必须明确推荐其中一项，不得回避或"中立呈现"
3. 取舍说明：
   • 每个非推荐方案：说明未选它的核心理由（一句话即可）
   • 推荐方案：说明选择它的核心理由 + 主要代价
4. 影响范围预测（blocker-revise 特有）：每个选项预测将影响哪些 artifact 需要修订，并粗估修订量（小改 / 中改 / 重写章节）
5. 使用工具：优先使用 question/choice 工具；工具不可用时以 markdown 形式直接呈现

强制语义（不得跳过）

• 触发条件命中时必须启动用户决策流程，即使你倾向"自己决定"或"按 blocker.md 建议执行"
• 即使用户回复"你看着办"，也必须回复"推荐方案 + 主要代价"，请用户显式确认推荐方案，不得默认接受"你看着办"作为决策
• 决策方向涉及扩展本次业务范围或引入核心新依赖时（触发条件 2），必须额外显式提示"本选项将扩展本次范围 / 引入新依赖"，并征得用户的明确同意（不接受默认）
• 用户未决策前不得进入步骤 5 的实际修订

决策归档规则

用户给出决策后：

1. 决策结论融入对应 artifact 的相关章节——不设独立的"决策记录"章节
2. 在 blocker.md 末尾追加"修订记录"段：记录选择方案、选择理由、修改的 artifacts 列表、被取消勾选的 tasks——这是审计线索，不是二次决策入口
3. 决策引发的修订如果触及 requirements / design 的关键决策，按各 artifact instruction 中"决策归档规则"融入对应章节
4. 决策结论应可在 apply 恢复后直接使用——明确到 apply 阶段无需重新发起决策

工作流

步骤 1: 阅读并理解阻塞

阅读 blocker.md，识别：

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

完成本步骤后进入步骤 2。

步骤 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。

步骤 3: 确定修订入口

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

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

如果"修订入口在不同 artifact 之间犹豫"（触发条件 3），先暂停并启动用户决策流程；用户决策后回到本步骤。

完成本步骤后进入步骤 4。

步骤 4: 用户决策

检查是否命中"用户决策流程（强制协议）"中任一触发条件：

• 命中 → 按强制格式输出候选 + 推荐 + 取舍 + 影响范围预测，等待用户决策
• 未命中 → 直接进入步骤 5（属于 AI 自决范围）

用户决策后或确认无需决策后，进入步骤 5。

步骤 5: 执行修订

从步骤 3 确定的修订入口开始，按 code-drive 正常流程逐层修订下游 artifacts。

子步骤 5.1: 读取 instruction 与 template

对每个待修订的 artifact：

1. 读取 schema.yaml 中该 artifact 的 instruction
2. 读取该 artifact 的 template
3. 后续修订必须遵循 instruction 工作流和 template 结构

子步骤 5.2: 局部修订

按修订范围原则执行：

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

子步骤 5.3: 保留已完成任务

按以下规则处理 tasks.md 中已完成任务：

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

完成本步骤后进入步骤 6。

步骤 6: 修订后验证

每个被修订的 artifact 完成后，按两层一致性检查。

子步骤 6.1: Instruction 合规性检查

• 每个被修订的 artifact 是否符合其 instruction 中的工作流和完成标准
• 每个被修订的 artifact 是否包含其 instruction / template 要求的章节
• 每个被修订的 artifact 是否符合其 template 结构

子步骤 6.2: 上下游一致性检查

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

任一项失败 → 回到步骤 5 局部修复，修复后从该项重跑。

全部通过后进入步骤 7。

步骤 7: 处理 blocker.md

按以下子步骤追加修订记录并归档。

子步骤 7.1: 追加修订记录

在 blocker.md 末尾追加：

## 修订记录

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

子步骤 7.2: 保留或归档

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

完成本步骤后进入步骤 8。

步骤 8: 完成

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

完成标准

• 工作流步骤 1-8 全部走过
• 步骤 6 的 instruction 合规性 + 上下游一致性全部通过
• blocker.md 已追加修订记录，并被保留或归档
• 选定的修订方向已记录在受影响 artifact 中
• 每个被修订的 artifact 符合其 instruction 的工作流和 template 结构
• 已完成任务的 checkbox 被保留，除非明确失效
• 所有触发条件命中时都执行了用户决策流程（事后可被审计）
• 用户知道需要重新运行 apply 继续实现

规则速查

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