# 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` 末尾追加“修订记录”：

```markdown
## 修订记录

- 选择方案：
- 选择理由：
- 修改的 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 继续实现。