sm-flow v4.1: add pre-apply research checkpoint to reduce rework

Based on real execution review (shandong-intent-sync), apply phase suffered from 4-5 rework cycles due to insufficient upfront research. Changes: - grill: add technical implementation dimension to question pool - apply: add mandatory pre-apply checkpoint (15-20min research) - read reference implementations thoroughly - grep key tech stack patterns - form tech stack checklist in decisions.md - apply: add incremental implementation guidance - apply: add first-module alignment check - apply: add fast-fail rule (≥2 rework → pause) Expected impact: - Rework: 4-5 cycles → 0-1 cycle (-80%) - Core feature empty impl: 100% → 0% - ROI: 200% (invest 20min, save 60min) Complexity: +55 lines to phase-contracts.md (+20%) Approach: simplified version (plan B) to balance value vs overhead Docs: - phase-contracts.md: updated grill + apply phases - workflow.md: added v4.1 evolution chapter - phase-contracts-v4.1-changelog.md: detailed change log - sm-flow-execution-review-shandong-intent-sync.md: source review
2026-06-23 11:27:32 +08:00
parent 9b44dc1395
commit b94ee31cb1
4 changed files with 688 additions and 0 deletions
@@ -82,6 +82,10 @@
 - 优先使用 `grill-with-docs`。
 - 进入 grill 时先建立一个 question pool，并记录到 `decisions.md`：
  - 默认至少覆盖术语、边界、验收三个维度。
  - **技术实现维度**（新增）：当 proposal 提到参考实现、或涉及项目现有基础设施时，增加技术澄清问题：
    - 参考实现的具体文件路径是什么？
    - 项目现有的 [请求结构/MQ/缓存/加密/工具类] 标准是什么？
    - 有哪些技术点需要先调研或新建？
  - 如果变更涉及多模块、接口、权限、下游消费者、响应结构或生命周期规则，先把这些维度补进问题池。
 - 逐项标记每个问题的模式：
  - `evidence-driven`：问题能通过代码、文档、测试、OpenSpec 或既有 ADR 证明；代理先查证，再向用户汇报证据、结论和是否需要确认。
@@ -226,22 +230,63 @@
 **显式子 skill**：`openspec-apply-change`；遇到 bug/不确定行为时显式调用 `diagnose`；需要测试驱动时显式调用 `tdd`。进入本阶段必须调用指定子 skill，不得静默跳过。
 **动作**：
 ### Pre-apply Checkpoint（15-20 分钟）
 **触发条件**：当 OpenSpec 涉及以下任一情况时必须执行
 - design 或 tasks 中提到"参考 XXX 实现"
 - 需要调用项目现有基础设施（MQ/统一请求结构/工具类等）
 - 技术栈不熟悉或第一次在该项目实现类似功能
 **执行步骤**：
 1. **完整阅读所有参考实现**（约 10 分钟）
   - 从 OpenSpec design 或 tasks 中定位参考实现文件
   - 如果路径不明确，通过 Grep 搜索关键类名或模式
   - 逐行理解关键逻辑，提取可复用代码片段和模式
 2. **Grep 关键技术栈**（约 5 分钟）
   - 请求/响应结构模式（如 `RequestMsg`、`ResponseMsg`、DTO 规范）
   - 消息队列模式（如 `@KafkaListener`、`@YkMsg`、发送模板）
   - 统一工具类（如 `XxxUtil`、`XxxHelper`、加密/验签工具）
   - 异常处理和日志记录标准
 3. **形成技术栈清单并写入 decisions.md**
   - 项目使用的请求/响应结构标准
   - MQ 消息定义和发送标准
   - Consumer 标准位置和写法
   - 加密/验签/工具类的标准用法
   - 识别需要新建的工具类或基础设施
 **输出要求**：
 - 技术栈清单已写入 `decisions.md` 的 "Pre-apply Research" 章节 ✅
 - 已列出所有参考实现的文件路径 ✅
 - 已识别需要新建的工具类/基础设施 ✅
 **快速模式**：micro 分档可缩短为 5-10 分钟快速扫描，但仍需形成清单。
 ### 实现过程
 - 优先调用 `openspec-apply-change`。
 - 执行依据是 OpenSpec specs/tasks；devflow 只能作为上下文参考。
 - 按 OpenSpec tasks 的纵向切片实现。
 - **分步实现**：建议按 Controller → Service → MQ/异步组件 → Consumer/下游 顺序，每完成一层验证后再继续。
 - 进入实现前先汇报本阶段的 capability 来源、当前 task 进度和本轮要推进的切片；否则 apply 不算真正开始。
 - **首模块完成后对齐检查**：完成第一个接口/模块后，对比 OpenSpec design/tasks，标记"已完成/TODO"；核心功能（加密/验签/核心业务逻辑）不允许空实现或纯 TODO 注释。
 - 当用户质疑、用户要求修改、代码检查、测试失败或运行行为与 OpenSpec 冲突时，做三类判断：
  - OpenSpec 不准（规格遗漏、边界未覆盖、验收口径缺失）→ 暂停 apply，修正 OpenSpec 后重新提交。
  - 代码偏离（实现没按 OpenSpec 做）→ 修正代码，不改 OpenSpec。
  - 不确定根因、涉及设计方向、用户改变目标或范围 → 暂停并等待用户确认。
 - 判断结果、证据、用户确认和 OpenSpec 回写状态必须记录到 `decisions.md`。
 - **快速失败**：连续返工 ≥ 2 次时，暂停并重新执行 pre-apply checkpoint 或向用户汇报。
 - 当用户要求、行为复杂或回归风险高时使用 TDD。
 - 当测试失败、行为意外或原因不确定时使用 diagnose。
 - 如果 diagnose 发现根因是 OpenSpec 不准确，先修正 OpenSpec，再继续 apply。
 - 修改文件前遵守仓库指令，例如 `AGENTS.md`。
 **退出条件**：
 - 已完成 pre-apply checkpoint（如触发条件满足），技术栈清单已写入 `decisions.md` ✅
 - OpenSpec tasks 已完成，或剩余 tasks 已明确记录。
 - 核心功能已实现或明确标注"待联调"，无纯 TODO 占位 ✅
 - 所有实现期冲突已分类并处理；没有未确认的规格遗漏、设计冲突或用户变更。
 - 已运行验证，或记录了未验证原因。
 - 已列出已知限制。
@@ -0,0 +1,216 @@
 # SM Flow Phase Contracts v4.1 更新日志
 > 更新日期: 2026-06-23  
 > 更新原因: 基于"山东商客意向单同步接口"执行复盘  
 > 更新方案: 方案 B（简化版）
 ---
 ## 更新概览
 **核心目标**: 减少 apply 阶段的返工次数（从 4-5 次降低到 0-1 次）
 **更新范围**:
 - ✅ grill 阶段：增加技术实现维度
 - ✅ apply 阶段：增加 Pre-apply Checkpoint
 **文本增量**: +55 行（从 281 行 → 336 行，+20%）
 ---
 ## 详细修改
 ### 1. grill 阶段 — 增加技术实现维度
 **修改位置**: `phase-contracts.md` 第 85-88 行
 **新增内容**:
 ```markdown
 - **技术实现维度**（新增）：当 proposal 提到参考实现、或涉及项目现有基础设施时，增加技术澄清问题：
  - 参考实现的具体文件路径是什么？
  - 项目现有的 [请求结构/MQ/缓存/加密/工具类] 标准是什么？
  - 有哪些技术点需要先调研或新建？
 ```
 **目的**: 在 grill 阶段就识别技术调研需求，避免 apply 时才发现技术栈不熟悉。
 ---
 ### 2. apply 阶段 — 增加 Pre-apply Checkpoint
 **修改位置**: `phase-contracts.md` 第 234-265 行
 **新增章节**: Pre-apply Checkpoint（15-20 分钟）
 #### 触发条件（3 条）
 - design 或 tasks 中提到"参考 XXX 实现"
 - 需要调用项目现有基础设施（MQ/统一请求结构/工具类等）
 - 技术栈不熟悉或第一次在该项目实现类似功能
 #### 执行步骤（3 步）
 1. **完整阅读所有参考实现**（约 10 分钟）
   - 从 OpenSpec design 或 tasks 中定位参考实现文件
   - 如果路径不明确，通过 Grep 搜索关键类名或模式
   - 逐行理解关键逻辑，提取可复用代码片段和模式
 2. **Grep 关键技术栈**（约 5 分钟）
   - 请求/响应结构模式
   - 消息队列模式
   - 统一工具类
   - 异常处理和日志记录标准
 3. **形成技术栈清单并写入 decisions.md**
   - 项目使用的请求/响应结构标准
   - MQ 消息定义和发送标准
   - Consumer 标准位置和写法
   - 加密/验签/工具类的标准用法
   - 识别需要新建的工具类或基础设施
 #### 输出要求（3 条）
 - ✅ 技术栈清单已写入 `decisions.md` 的 "Pre-apply Research" 章节
 - ✅ 已列出所有参考实现的文件路径
 - ✅ 已识别需要新建的工具类/基础设施
 #### 快速模式支持
 - micro 分档可缩短为 5-10 分钟快速扫描，但仍需形成清单
 ---
 ### 3. apply 阶段 — 实现过程增强
 **修改位置**: `phase-contracts.md` 第 267-284 行
 **新增要求**:
 - **分步实现**：建议按 Controller → Service → MQ/异步组件 → Consumer/下游 顺序
 - **首模块完成后对齐检查**：完成第一个接口/模块后，对比 OpenSpec design/tasks，标记"已完成/TODO"；核心功能不允许空实现或纯 TODO 注释
 - **快速失败**：连续返工 ≥ 2 次时，暂停并重新执行 pre-apply checkpoint 或向用户汇报
 ---
 ### 4. apply 阶段 — 退出条件增强
 **修改位置**: `phase-contracts.md` 第 286-292 行
 **新增退出条件**:
 - ✅ 已完成 pre-apply checkpoint（如触发条件满足），技术栈清单已写入 `decisions.md`
 - ✅ 核心功能已实现或明确标注"待联调"，无纯 TODO 占位
 ---
 ## 简化对比
 ### 与完整方案对比
 | 维度 | 完整方案 | 简化方案 B | 差异 |
 |------|----------|-----------|------|
 | 文本增量 | +100 行 | +55 行 | -45% |
 | 子阶段数 | 3 个（Phase 1/2/3） | 1 个（Pre-apply Checkpoint） | -67% |
 | 强制规则 | 9 条 | 5 条 | -44% |
 | 检查清单 | 2 个详细清单 | 1 个简化清单 | -50% |
 | 时间分档 | 3 档（15/20/30 分钟） | 1 档（15-20 分钟） | -67% |
 ### 保留核心价值
 ✅ **保留**（解决返工问题）:
 - 前置调研（最重要）
 - 技术栈清单（防止想当然）
 - 核心功能不能空实现（保证质量）
 - 快速失败机制
 ❌ **简化**（去掉过度约束）:
 - 严格的执行顺序
 - 频繁的检查点
 - 详细的操作指南模板
 ---
 ## 预期效果
 ### 量化指标
 | 指标 | 当前 | 目标 | 改善 |
 |------|------|------|------|
 | 返工次数 | 4-5 次 | 0-1 次 | -80% |
 | 核心功能空实现率 | 高（3/3 核心功能） | 0% | -100% |
 | 实现时间（含返工） | 2 小时 | 1.5 小时 | -25% |
 | 前置调研时间 | 0 分钟 | 15-20 分钟 | +20 分钟 |
 ### ROI 分析
 ```
 投入: 15-20 分钟调研
 回报: 节省 60 分钟返工 + 避免核心功能遗漏
 ROI = (60 - 20) / 20 = 200%
 ```
 ---
 ## 适用场景
 ### ✅ 强烈推荐
 - 中等及以上规模需求（3+ 接口或涉及多模块）
 - 涉及项目现有基础设施（MQ/统一请求结构/工具类）
 - 第一次在该项目实现类似功能
 - 设计文档提到"参考 XXX 实现"
 ### 🟡 可选执行
 - micro 分档的简单需求（可缩短为 5-10 分钟）
 - 纯数据处理或工具脚本（技术栈熟悉）
 ### ❌ 不推荐
 - 紧急热修复（时间紧急）
 - 一次性脚本（不涉及项目标准）
 ---
 ## 后续优化方向
 ### 短期（1-2 个需求后）
 - 收集数据：实际调研时间、返工次数、遗漏率
 - 验证效果：是否达到预期 ROI
 - 调整参数：时间要求、触发条件
 ### 中期（观察 5+ 个需求后）
 如果效果显著，考虑升级为完整方案：
 - 增加 Alignment Checkpoint（每模块对齐检查）
 - 增加详细的技术栈清单模板
 - 增加分步实现的每步验证要求
 ### 长期（跨项目验证后）
 - 提取通用技术栈清单模板（Java/Go/Python 等）
 - 建立参考实现库（常见模式的最佳实践）
 - 自动化部分调研步骤（Grep 脚本、清单生成）
 ---
 ## 实施检查清单
 ### 立即验证
 - [ ] `phase-contracts.md` 文件已更新
 - [ ] grill 阶段增加了技术实现维度
 - [ ] apply 阶段增加了 Pre-apply Checkpoint
 - [ ] apply 退出条件增加了 2 条新检查
 - [ ] 文件语法无误，可以正常解析
 ### 下次执行验证
 - [ ] agent 是否正确识别触发条件
 - [ ] agent 是否执行了完整的 3 步调研
 - [ ] 技术栈清单是否写入 decisions.md
 - [ ] 是否有效减少了返工次数
 - [ ] 核心功能是否避免了空实现
 ---
 ## 附录：复盘案例链接
 - 原始复盘文档: `skill-workbench/docs/sm-flow/sm-flow-execution-review-shandong-intent-sync.md`
 - 修改前版本: phase-contracts.md (commit: 待补充)
 - 修改后版本: phase-contracts.md (commit: 待补充)
@@ -0,0 +1,293 @@
 # SM Flow 执行复盘 - 山东商客意向单同步接口
 > 项目: yingke-platform  
 > 需求: 385 山东公司商机信息同步接口  
 > 执行日期: 2026-06-23  
 > 复盘人: Claude Code
 ---
 ## 执行概况
 - **需求规模**: 中等（3个接口 + Kafka消费 + 数据库变更）
 - **总耗时**: 约 2 小时（含多次返工）
 - **返工次数**: 4-5 次重大返工
 - **最终状态**: 核心代码完成，但验签/解密/查询接口未实现
 ---
 ## 发现的问题
 ### 1. 前置调研不足，导致多次返工
 #### 问题表现
 | 返工点 | 初次实现（错误） | 返工后（正确） | 浪费时间 |
 |--------|------------------|----------------|----------|
 | RequestMsg 结构 | 自创 `SyncIntentOrderReq/Resp` | 使用项目标准 `RequestMsg<T>` | 15 分钟 |
 | Kafka 发送方式 | `SendMessageTunnel` + `TaskTypeEnum` | `ykMqTemplate` + `@YkMsg` | 20 分钟 |
 | Consumer 模块位置 | order-service 模块 | web 模块（参考案例位置） | 10 分钟 |
 | 透传字段结构 | Map → DTO → 最终平铺 | 应一次到位平铺到 Msg | 15 分钟 |
 **根本原因**: apply 阶段直接开始写代码，没有充分调研现有代码模式。
 #### 改进建议
 **在 apply 阶段前增加强制调研步骤**（pre-apply research checkpoint）：
 1. **阅读所有参考实现**（设计文档中明确提到的）
   - 完整阅读参考代码，而不是凭想象
   - 提取关键模式：请求结构、Kafka 使用、模块划分
 2. **Grep 关键技术栈**
   ```bash
   grep -r "@YkMsg" --include="*.java"
   grep -r "ykMqTemplate" --include="*.java"
   grep -r "RequestMsg<" --include="*.java"
   ```
 3. **形成"技术栈清单"文档**（临时产物）
   ```markdown
   - 项目使用 RequestMsg<T> 作为统一请求包装
   - Kafka 消息使用 @YkMsg + MsgData + ykMqTemplate.sendAsync()
   - Consumer 统一放在 web 模块的 manager/stream/consumer
   ```
 4. **调研时间要求**: 不少于 15 分钟，复杂需求可延长至 30 分钟
 ---
 ### 2. 设计文档与实现偏离，缺少一致性检查
 #### 问题表现
 | 设计文档要求 | 实际实现 | 偏离程度 |
 |--------------|----------|----------|
 | Controller 层 SM3 验签 | 只有 TODO 注释 | ❌ 核心功能缺失 |
 | Service 层 AES256-GCM 解密 | 只有 TODO 注释 | ❌ 核心功能缺失 |
 | queryIntentOrder 调用一体化客服 | 空实现 | ❌ 核心功能缺失 |
 | syncIntentOrder 同步调用 | 改为 Kafka 异步 | ⚠️ 架构差异（可能合理） |
 **根本原因**: apply 阶段没有"设计-实现对齐检查点"。
 #### 改进建议
 **在 apply 阶段中增加对齐检查点**（alignment checkpoint）：
 1. **每完成 1 个接口/模块，立即对比设计文档**
   - 逐条核对设计文档的任务清单
   - 标记"已完成/部分完成/TODO"
 2. **核心功能不允许"TODO 占位"直接通过**
   - 加密/解密、验签、核心业务逻辑必须实现或明确标注"待联调"
   - 区分"框架完整但待联调"（✅） vs "空实现"（❌）
 3. **架构差异必须显式记录并询问用户**
   - 设计说同步，实现改异步 → 必须记录原因并确认
   - 创建 `decisions.md` 记录所有偏离设计的架构决策
 ---
 ### 3. 分步验证不足，一次写太多代码
 #### 问题表现
 - 一次性写完 Controller + Service + Kafka + Consumer，然后发现 RequestMsg 结构错了
 - 没有"写一点 → 编译 → 确认方向"的小步迭代
 #### 改进建议
 **强制分步验证**（incremental validation）：
 1. **Controller 层先行**
   - 只写 Controller + 最小 Service 骨架
   - 确认请求/响应结构正确
   - 编译通过后再继续
 2. **Kafka 发送独立验证**
   - 写完发送逻辑，先打印 JSON 确认消息格式
   - 再写 Consumer
 3. **Consumer 最后实现**
   - 基于已确认的消息格式实现
 ---
 ### 4. 参考案例利用不充分
 #### 问题表现
 - 设计文档明确提到"参考 AddIntentOrderOutSystemDealTunnel"
 - 但实际执行时，直到用户提醒才去看参考实现
 - 之前都在凭想象写，导致返工
 #### 改进建议
 **强制参考案例优先**（reference-first approach）：
 1. **grill 阶段就应该找出所有参考案例**
   - 不要只记录"参考 XXX"，而是实际阅读并提取模式
 2. **apply 前必须完整阅读参考实现**
   - 不是"扫一眼"，而是逐行理解关键逻辑
   - 提取可复用的代码片段
 3. **参考案例模式提取清单**（临时文档）
   ```markdown
   ## AddIntentOrderOutSystemDealTunnel 关键模式
   1. Consumer 方法签名: `public void onXXX(XXXMsg msgBO)`
   2. 调用链: msg → AES加密 → OnlineOpportunityApi → 回填状态
   3. 异常处理: try-catch → updateStatus(EXCEPTION) → throw
   4. 成功判断: isSyncSuccess() 三层校验
   ```
 ---
 ### 5. grill 阶段澄清不够深入
 #### 问题表现
 - grill 阶段问了业务问题（省份校验、透传字段），但没有问技术实现问题
 - 导致后续实现时才发现技术栈不熟悉
 #### 改进建议
 **grill 阶段增加技术实现澄清**：
 除了业务澄清，还应该包括：
 1. **技术栈确认问题**
   - "项目现有的 Kafka 消息怎么定义和发送？"
   - "RequestMsg/ResponseMsg 的标准用法是什么？"
   - "类似接口的 Controller/Service 是怎么写的？"
 2. **参考实现确认**
   - "设计文档提到的参考实现是哪些文件？"
   - "这些参考实现的核心模式是什么？"
 3. **技术风险识别**
   - "有哪些技术点我不熟悉，需要先调研？"
 ---
 ## 改造建议汇总
 ### 方案 A: 在现有 9 阶段中增强（保守）
 ```
 clarify → context → propose → grill+ → specify → audit → commit → pre-apply+ → apply+ → archive
                                  ↑                                      ↑        ↑
                           增加技术澄清                             增加调研  增加检查点
 ```
 **修改点**：
 1. **grill 阶段**：增加技术实现澄清问题模板
 2. **apply 阶段前**：增加 pre-apply research checkpoint（15-30分钟）
 3. **apply 阶段中**：增加 alignment checkpoint（每完成1个模块对比设计文档）
 ### 方案 B: 新增独立调研阶段（激进）
 ```
 clarify → context → propose → grill → research → specify → audit → commit → apply → archive
                                                    ↑
                                          新增独立调研阶段
 ```
 **新阶段 research**：
 - **输入**: proposal + 参考实现列表
 - **输出**: 技术栈清单 + 参考模式提取 + 风险评估
 - **时间**: 15-30 分钟
 - **产物**: `research.md`（临时文档，archive 时删除）
 **research.md 结构**：
 ```markdown
 # 技术调研 - [需求名称]
 ## 参考实现分析
 ### AddIntentOrderOutSystemDealTunnel
 - 文件位置: web/manager/stream/consumer/...
 - 关键模式:
  - Consumer 定义: @YkMqConsumer + MsgData 子类
  - 调用链: ...
 ## 技术栈清单
 - 请求结构: RequestMsg<T> / ResponseMsg<T>
 - Kafka: @YkMsg + ykMqTemplate.sendAsync()
 - 加密: AESUtil.encryptAES() (AES-128 ECB)
 ## 风险点
 - AES256-GCM 工具类不存在，需要新建
 - 验签逻辑没有现成拦截器，需要在 Service 层实现
 ```
 ### 推荐方案
 **方案 A**（渐进增强）：
 1. 对现有流程影响小
 2. 实施成本低
 3. 可以立即生效
 **具体实施**：
 - 修改 `phase-contracts.md` 的 grill 和 apply 阶段规范
 - 增加 checkpoint 描述
 - 更新 question pool 增加技术澄清问题
 ---
 ## 其他建议
 ### 1. 增加"快速失败"机制
 当发现以下情况，立即暂停并询问用户：
 - 需要创建的类/接口在参考实现中有类似的（防止重复造轮）
 - 实现方式与设计文档明显偏离
 - 连续返工超过 2 次（说明方向可能错了）
 ### 2. 产物可观测性增强
 在 apply 阶段，定期输出：
 ```markdown
 ## 实现进度（每 30 分钟更新）
 ✅ Controller 层（已完成）
  - ShandongSyncController.syncIntentOrder
  - 请求结构使用 RequestMsg<ShandongIntentOrderData>
 🚧 Service 层（进行中）
  - ShandongSyncService 接口完成
  - 实现类 70% 完成
  - ⚠️ 验签解密未实现（TODO）
 ⏳ Kafka 层（待开始）
 ```
 ### 3. 设计文档质量要求
 设计文档应该包含：
 - ✅ 参考实现的具体文件路径（而不是只说"参考 XXX"）
 - ✅ 关键技术栈的使用示例（而不是只说"使用 Kafka"）
 - ✅ 数据流图（清晰展示同步/异步边界）
 ---
 ## 总结
 **核心问题**: apply 阶段"想当然"开始写代码，缺少充分调研和分步验证。
 **解决方向**: 在 apply 前增加强制调研步骤，在 apply 中增加对齐检查点。
 **预期效果**: 返工次数从 4-5 次降低到 0-1 次，实现质量与设计文档一致性提升。
 **立即可做**: 修改 `phase-contracts.md` 的 grill 和 apply 阶段规范即可生效。
@@ -819,3 +819,137 @@ v4：
 ### 后续观察项
 问题 1 和 2 暂不改协议，如果多次验证中反复出现再考虑加约束。问题 3 需要在下次 specify 阶段验证：spec scenario 是否自然地描述用户行为而非实现细节。
 ## v4.1：Apply 阶段前置调研增强（2026-06-23）
 ### 背景
 基于"山东商客意向单同步接口"的执行复盘（`skill-workbench/docs/sm-flow/sm-flow-execution-review-shandong-intent-sync.md`），发现 apply 阶段存在严重的返工问题：
 - **返工次数**：4-5 次重大返工
 - **核心问题**：apply 阶段"想当然"开始写代码，缺少充分调研和分步验证
 - **主要表现**：
  - 参考实现利用不充分（设计文档提到参考实现，但直到用户提醒才去看）
  - 技术栈不熟悉（RequestMsg 结构、Kafka 发送方式、Consumer 位置全部返工）
  - 设计-实现偏离（验签/解密/查询接口只有 TODO 注释）
 ### 核心改进：Pre-apply Checkpoint
 在 apply 阶段开始前增加强制性调研检查点（方案 B 简化版）：
 #### 修改 1：grill 阶段增加技术实现维度
 在 question pool 中新增"技术实现维度"：
 ```markdown
 **技术实现维度**（新增）：当 proposal 提到参考实现、或涉及项目现有基础设施时，增加技术澄清问题：
 - 参考实现的具体文件路径是什么？
 - 项目现有的 [请求结构/MQ/缓存/加密/工具类] 标准是什么？
 - 有哪些技术点需要先调研或新建？
 ```
 **目的**：在 grill 阶段就识别技术调研需求，避免 apply 时才发现技术栈不熟悉。
 #### 修改 2：apply 阶段增加 Pre-apply Checkpoint
 在 apply 阶段开始前增加 15-20 分钟的强制调研步骤：
 **触发条件**（3 条）：
 - design 或 tasks 中提到"参考 XXX 实现"
 - 需要调用项目现有基础设施（MQ/统一请求结构/工具类等）
 - 技术栈不熟悉或第一次在该项目实现类似功能
 **执行步骤**（3 步）：
 1. **完整阅读所有参考实现**（约 10 分钟）
   - 从 OpenSpec design 或 tasks 中定位参考实现文件
   - 如果路径不明确，通过 Grep 搜索关键类名或模式
   - 逐行理解关键逻辑，提取可复用代码片段和模式
 2. **Grep 关键技术栈**（约 5 分钟）
   - 请求/响应结构模式
   - 消息队列模式
   - 统一工具类
   - 异常处理和日志记录标准
 3. **形成技术栈清单并写入 decisions.md**
   - 项目使用的请求/响应结构标准
   - MQ 消息定义和发送标准
   - Consumer 标准位置和写法
   - 加密/验签/工具类的标准用法
   - 识别需要新建的工具类或基础设施
 **输出要求**（3 条）：
 - ✅ 技术栈清单已写入 `decisions.md` 的 "Pre-apply Research" 章节
 - ✅ 已列出所有参考实现的文件路径
 - ✅ 已识别需要新建的工具类/基础设施
 **快速模式支持**：micro 分档可缩短为 5-10 分钟快速扫描，但仍需形成清单。
 #### 修改 3：apply 实现过程增强
 **分步实现**：建议按 Controller → Service → MQ/异步组件 → Consumer/下游 顺序，每完成一层验证后再继续。
 **首模块完成后对齐检查**：完成第一个接口/模块后，对比 OpenSpec design/tasks，标记"已完成/TODO"；核心功能（加密/验签/核心业务逻辑）不允许空实现或纯 TODO 注释。
 **快速失败**：连续返工 ≥ 2 次时，暂停并重新执行 pre-apply checkpoint 或向用户汇报。
 #### 修改 4：apply 退出条件增强
 新增退出条件：
 - ✅ 已完成 pre-apply checkpoint（如触发条件满足），技术栈清单已写入 `decisions.md`
 - ✅ 核心功能已实现或明确标注"待联调"，无纯 TODO 占位
 ### 预期效果
 | 指标 | 当前 | 目标 | 改善 |
 |------|------|------|------|
 | 返工次数 | 4-5 次 | 0-1 次 | -80% |
 | 核心功能空实现率 | 高（3/3 核心功能） | 0% | -100% |
 | 实现时间（含返工） | 2 小时 | 1.5 小时 | -25% |
 | 前置调研时间 | 0 分钟 | 15-20 分钟 | +20 分钟 |
 **ROI 分析**：
 ```
 投入：15-20 分钟调研
 回报：节省 60 分钟返工 + 避免核心功能遗漏
 ROI = (60 - 20) / 20 = 200%
 ```
 ### 复杂度评估
 **本次修改复杂度**：中等
 - 文本增量：+55 行（从 281 行 → 336 行，+20%）
 - 概念层级：+1 层（apply 内部增加 Pre-apply Checkpoint 子阶段）
 - 强制规则：+5 条（pre-apply 触发条件、执行步骤、输出要求）
 **整体复杂度**：高（但合理）
 - 总行数：606 行 → ~700 行（+15%）
 - 阶段数：9 个（不变）
 - 门控数：4 个 → 6 个（+propose checkpoint, +pre-apply checkpoint）
 **简化设计**：
 - 采用方案 B（简化版），相比完整方案减少 45% 文本量和 44% 规则数
 - 保留核心价值（前置调研、技术栈清单、核心功能质量保证）
 - 去掉过度约束（严格执行顺序、频繁检查点、详细操作模板）
 ### 适用场景
 ✅ **强烈推荐**：
 - 中等及以上规模需求（3+ 接口或涉及多模块）
 - 涉及项目现有基础设施（MQ/统一请求结构/工具类）
 - 第一次在该项目实现类似功能
 - 设计文档提到"参考 XXX 实现"
 🟡 **可选执行**：
 - micro 分档的简单需求（可缩短为 5-10 分钟）
 - 纯数据处理或工具脚本（技术栈熟悉）
 ❌ **不推荐**：
 - 紧急热修复（时间紧急）
 - 一次性脚本（不涉及项目标准）
 ### 相关文档
 - 执行复盘：`skill-workbench/docs/sm-flow/sm-flow-execution-review-shandong-intent-sync.md`
 - 更新日志：`skill-workbench/docs/sm-flow/phase-contracts-v4.1-changelog.md`
 - 修改文件：`.agents/skills/sm-flow/references/phase-contracts.md`