133 lines
5.5 KiB
Markdown
133 lines
5.5 KiB
Markdown
# 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 继续实现。
|