235 lines
12 KiB
Markdown
235 lines
12 KiB
Markdown
# 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` 末尾追加：
|
||
|
||
```markdown
|
||
## 修订记录
|
||
|
||
- 选择方案：
|
||
- 选择理由：
|
||
- 修改的 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
|