增强需求审查并在用户确认后推进

docs/design/active/2026-10-01-requirement-review-confirmation.md

@@ -0,0 +1,49 @@
+# 对内-已确认：需求审查与用户确认流程设计
+
+## Related issue
+
+- https://github.com/HaodiFan/engineering-everything/issues/21
+- 状态：优化方案与修改范围已确认；合并状态以关联 PR 为准。
+
+## Optimization goal / 优化目标
+
+AI 从已有材料查证需求，审查业务闭环与规则缺口，提出有依据的建议；用户明确确认结论、取舍和下一步后，再更新需求并推进。
+
+## Direction / 优化方向
+
+沿用产品定义 Skill、需求完备性检查与需求模板，补足审查到推进的交接。保持事实、假设、建议和用户决策可区分。审查报告由 Checklist 定义，Skill 只引用该格式。
+
+## Implementation plan / 实现范围
+
+1. `skills/engineering-product-definition/SKILL.md` 增加审需求入口，先查证已有材料，再分级审查、提出建议并等待确认；实际确认的决策直接沿用。
+2. `references/checklists.md` 增加审查顺序、必须先解决与可后置的缺口分级，以及关键缺口的证据、影响、候选方案、代价与推荐理由。`PASS` 仅表示覆盖充分，确认状态单独记录。
+3. `references/templates-specs.md` 补充材料来源、待确认假设、业务流程与规则对应的验收样例，以及实际用户确认记录。权限、审批和集成字段按场景适用。
+4. 按 `data/reference_distribution.yaml` 同步十个 runtime reference copies。
+
+## Verification plan / 验证
+
+执行 `docs/testing.md` 所列仓库检查，并检查本次三个合成场景的规则覆盖：
+
+| 场景 | 预期处理 | 手工走查依据 |
+|---|---|---|
+| 驳回后可重新提交，未明确审批路径 | 说明关键缺口及影响，比较候选路径，建议保持待确认 | Checklist 审查顺序 2–4；Requirements 的规则与验收、待决事项 |
+| 需求已完整，用户要求先审查，尚未同意下一步 | 完备性可为 PASS，确认状态仍为待确认，保持审查阶段 | Checklist 对 PASS 的定义与确认状态；Skill 工作流 4 |
+| 用户只回答一个问题，随后确认剩余取舍及下一步 | 部分答复只关闭对应问题；确认后更新需求，已有决策不反复索取 | Skill 工作流 4–5；Checklist 审查顺序 5、确认记录 |
+
+以上为规则手工走查，未运行独立模型行为评估，不将结构检查作为模型遵循效果的证据。
+
+验证结果：reference distribution、eval scenario schema、Skill doctor、自进化检查、lesson 校验、脚本语法检查与 diff 检查均通过；现有十项单元测试全部通过。结构、canonical source 和显式指定本设计的 PR preflight 均通过。
+
+## Release plan / 发布计划
+
+Issue → focused branch → PR → 检查通过后合并到 main。此次只合并已确认的需求审查改进，不创建版本 tag 或 GitHub Release。变更说明与验收依据记录在本设计及 PR 中；Harness 配置和维护文件保持现状。
+
+## Risks and rollback / 风险与回退
+
+- 确认要求仅在产品定义和需求审查路径生效，已有明确确认直接沿用；新增关键假设或范围变化才重新确认。
+- 自然语言规则的真实模型遵循效果仍需独立行为评估。
+- 合并前可撤回本 PR；合并后可通过 revert 合并提交恢复本次修改。
+
+## Evidence boundary / 证据边界
+
+仅包含公开仓库相对路径、合成案例、改进范围、Issue 链接与验证依据。

references/checklists.md

@@ -68,9 +68,17 @@ npm run build
 
 ## 需求文档完备性 Checklist（Stage 1 用）
 
-> Agent 收到用户给的需求文档后，按这套清单校验。**全过才进 Stage 2**。
+> Agent 收到需求材料或被要求审查需求时，先查证、再审查、提出建议，等待用户确认后推进。`PASS` 只表示需求覆盖充分；进入下一阶段还须有用户对结论、取舍和下一步的明确确认。
 
-### 必须项（任何一项缺失 → 退回用户补）
+### 审查顺序
+
+1. 从用户材料和相关已有文档中提取目标、角色、场景、范围与约束，记录来源。文档冲突或无法查证时标明不确定性；业务意图由用户确认。
+2. 沿主流程检查触发、处理、交接和完成条件，核对范围、业务规则与验收是否一致。跨角色、审批或集成场景按需检查权限、状态流转和数据来源；关注重复提交、驳回、超时、无权限等与本需求相关的异常。
+3. 将缺口分为“必须先解决”和“可后置”。缺口会改变核心流程、范围、权限、数据口径或完成判定时须先解决；可后置项须说明适用边界、影响及关闭时点，由用户确认后置。
+4. 每个关键缺口写明证据、影响、可选方案、代价和推荐理由。依据不足时给出验证路径；建议保持待确认状态，禁止补写未确认规则或扩大范围。
+5. 汇总需要用户确认的需求理解、业务规则、范围取舍和下一步。未确认前继续停留在查证与审查；部分答复仅关闭对应事项，已有明确确认不重复索取。
+
+### 必须项（缺失 → 先查证，再带影响与建议请用户确认）
 
 - [ ] 业务背景：能解释"为什么做"
 - [ ] 目标用户：至少 1 类用户的场景与痛点
@@ -80,14 +88,17 @@ npm run build
 - [ ] 非目标：明确这一版不做什么
 - [ ] 关键约束：合规 / 性能 / 时间 / 预算 至少一项明确
 - [ ] Owner：可对接的负责人
+- [ ] 业务闭环：触发、处理、交接和完成条件明确，P0 能独立完成核心任务
+- [ ] 规则与验收：关键规则和相关异常都有可观察的预期结果
+- [ ] 场景适用项：涉及权限、审批、状态流转、数据口径或集成时，相关边界和依赖明确；不适用项说明原因
 
 ### 应有项（缺失但可推迟）
 
 - [ ] P1 / Later 列表
 - [ ] 已知风险
 - [ ] 与现有系统的关系
 
-### 危险信号（命中任一 → 立即提问，不要往下做）
+### 危险信号（命中任一 → 查证并解释影响，提出建议，等待用户决策）
 
 - [ ] 出现"差不多就行 / 你看着办 / 行业标准"等模糊词，且不肯具体化
 - [ ] 验收标准全是主观词（好用、流畅、漂亮）
@@ -96,17 +107,23 @@ npm run build
 - [ ] 成功指标不可量化或无截止时间
 - [ ] 性能/合规约束与所选架构明显冲突
 - [ ] 只有功能愿望，没有 Persona / Scenario / Pain 的证据
+- [ ] 角色权限、状态流转或验收与业务规则互相矛盾
+- [ ] 用拆分 MVP 删除了完成核心任务必需的规则、权限或异常处理
 
 ### Agent 输出格式
 
 ```text
 需求文档完备性: <PASS | NEEDS-USER-INPUT | BLOCKED>
-缺失必须项: <逐条列出>
-建议补充项: <逐条列出>
-需用户回答的问题: <编号列表>
-可继续推进的部分: <如可先做架构选型部分>
+需求理解: <目标、角色/场景、核心流程、本期范围；注明来源及待确认假设>
+缺失必须项: <逐项列出证据、影响、可选方案/代价、推荐理由>
+建议补充项: <可后置问题、影响、建议边界及关闭时点>
+需用户确认的事项: <编号列出理解、规则、范围取舍和下一步>
+确认状态: <待确认 | 部分确认 | 已确认；关联用户实际确认的事项与需求版本>
+可继续推进的部分: <未确认时仅查证和完善审查；确认后按约定范围推进>
 ```
 
+`NEEDS-USER-INPUT` 表示关键业务信息或决策待确认；`BLOCKED` 表示核心矛盾尚无可行闭环。禁止把未回复、沉默或检查通过记为用户确认。
+
 ---
 
 ## 新项目 Checklist（Stage 4 完成判定）

references/templates-specs.md

@@ -1,8 +1,10 @@
 # 需求、设计与交付模板
 
-用于创建 Requirements Doc、Design Doc、Layout Spec 和 PR Body。业务需求由用户/owner 提供；agent 只能结构化、校验、提问，不替用户编造业务意图。
+用于创建 Requirements Doc、Design Doc、Layout Spec 和 PR Body。业务意图由用户/owner 提供；agent 从已有材料提取、查证、结构化并提出建议，未确认的内容须标明。
 
-## Requirements Doc（用户提供）
+## Requirements Doc（基于用户材料）
+
+已有文档直接补充缺失内容，避免重复填表。按场景保留适用字段；建议和假设先作为审查结果给用户确认，确认后再更新需求正文。`reviewed` / `locked` 须对应用户实际确认，审查通过不能自动改变状态。
 
 ```md
 # Requirements: <Product/Feature> v0.0.1
@@ -13,7 +15,7 @@
 
 ## 业务背景
 
-<为什么做、当前问题、机会。由用户填写。>
+<从用户材料提取为什么做、当前问题、机会；注明来源，缺失项附建议请用户确认。>
 
 ## 目标用户与场景
 
@@ -28,6 +30,11 @@
 | 执行者 | | | 最少必填、默认值、下一步动作 |
 | 协作者 / 外部角色 | | | 权限、通知、交接、验收 |
 
+## 资料来源与待确认假设
+
+- 来源：<材料 / 文档位置及版本>
+- 待确认假设：<内容、依据、影响；确认后更新对应正文>
+
 ## 业务目标
 
 - 一句话目标：
@@ -38,7 +45,16 @@
 
 1. **<功能名>**
    - 用户价值：
-   - 验收标准：
+   - 验收标准：<前置条件 / 用户动作 / 可观察结果；关联下方规则或异常>
+
+## 核心流程、规则与验收
+
+- 主流程：<触发 → 处理 → 交接 → 完成条件>
+
+| 场景 / 异常 | 业务规则 | 预期结果 / 验收样例 |
+|---|---|---|
+
+<涉及跨角色或审批时补充谁可执行什么操作、可见哪些数据、如何流转；涉及数据或集成时补充来源、口径、依赖与失败处理。只保留适用内容，未确认规则保持待决。>
 
 ## P1 / Later
 
@@ -54,9 +70,15 @@
 
 ## 已知风险
 
-## Open Questions（用户回答）
+## Open Questions（待决事项）
+
+- [ ] Q1: <问题 / 影响 / 可选方案及代价 / 推荐理由 / 决策人>
+
+## 用户确认记录
 
-- [ ] Q1:
+- 确认的需求版本与事项：<关联用户实际答复>
+- 已确认后置项：<影响边界 / 关闭时点>
+- 约定的下一步：
 ```
 
 ## Design Doc

skills/engineering-architecture-design/references/checklists.md

@@ -68,9 +68,17 @@ npm run build
 
 ## 需求文档完备性 Checklist（Stage 1 用）
 
-> Agent 收到用户给的需求文档后，按这套清单校验。**全过才进 Stage 2**。
+> Agent 收到需求材料或被要求审查需求时，先查证、再审查、提出建议，等待用户确认后推进。`PASS` 只表示需求覆盖充分；进入下一阶段还须有用户对结论、取舍和下一步的明确确认。
 
-### 必须项（任何一项缺失 → 退回用户补）
+### 审查顺序
+
+1. 从用户材料和相关已有文档中提取目标、角色、场景、范围与约束，记录来源。文档冲突或无法查证时标明不确定性；业务意图由用户确认。
+2. 沿主流程检查触发、处理、交接和完成条件，核对范围、业务规则与验收是否一致。跨角色、审批或集成场景按需检查权限、状态流转和数据来源；关注重复提交、驳回、超时、无权限等与本需求相关的异常。
+3. 将缺口分为“必须先解决”和“可后置”。缺口会改变核心流程、范围、权限、数据口径或完成判定时须先解决；可后置项须说明适用边界、影响及关闭时点，由用户确认后置。
+4. 每个关键缺口写明证据、影响、可选方案、代价和推荐理由。依据不足时给出验证路径；建议保持待确认状态，禁止补写未确认规则或扩大范围。
+5. 汇总需要用户确认的需求理解、业务规则、范围取舍和下一步。未确认前继续停留在查证与审查；部分答复仅关闭对应事项，已有明确确认不重复索取。
+
+### 必须项（缺失 → 先查证，再带影响与建议请用户确认）
 
 - [ ] 业务背景：能解释"为什么做"
 - [ ] 目标用户：至少 1 类用户的场景与痛点
@@ -80,14 +88,17 @@ npm run build
 - [ ] 非目标：明确这一版不做什么
 - [ ] 关键约束：合规 / 性能 / 时间 / 预算 至少一项明确
 - [ ] Owner：可对接的负责人
+- [ ] 业务闭环：触发、处理、交接和完成条件明确，P0 能独立完成核心任务
+- [ ] 规则与验收：关键规则和相关异常都有可观察的预期结果
+- [ ] 场景适用项：涉及权限、审批、状态流转、数据口径或集成时，相关边界和依赖明确；不适用项说明原因
 
 ### 应有项（缺失但可推迟）
 
 - [ ] P1 / Later 列表
 - [ ] 已知风险
 - [ ] 与现有系统的关系
 
-### 危险信号（命中任一 → 立即提问，不要往下做）
+### 危险信号（命中任一 → 查证并解释影响，提出建议，等待用户决策）
 
 - [ ] 出现"差不多就行 / 你看着办 / 行业标准"等模糊词，且不肯具体化
 - [ ] 验收标准全是主观词（好用、流畅、漂亮）
@@ -96,17 +107,23 @@ npm run build
 - [ ] 成功指标不可量化或无截止时间
 - [ ] 性能/合规约束与所选架构明显冲突
 - [ ] 只有功能愿望，没有 Persona / Scenario / Pain 的证据
+- [ ] 角色权限、状态流转或验收与业务规则互相矛盾
+- [ ] 用拆分 MVP 删除了完成核心任务必需的规则、权限或异常处理
 
 ### Agent 输出格式
 
 ```text
 需求文档完备性: <PASS | NEEDS-USER-INPUT | BLOCKED>
-缺失必须项: <逐条列出>
-建议补充项: <逐条列出>
-需用户回答的问题: <编号列表>
-可继续推进的部分: <如可先做架构选型部分>
+需求理解: <目标、角色/场景、核心流程、本期范围；注明来源及待确认假设>
+缺失必须项: <逐项列出证据、影响、可选方案/代价、推荐理由>
+建议补充项: <可后置问题、影响、建议边界及关闭时点>
+需用户确认的事项: <编号列出理解、规则、范围取舍和下一步>
+确认状态: <待确认 | 部分确认 | 已确认；关联用户实际确认的事项与需求版本>
+可继续推进的部分: <未确认时仅查证和完善审查；确认后按约定范围推进>
 ```
 
+`NEEDS-USER-INPUT` 表示关键业务信息或决策待确认；`BLOCKED` 表示核心矛盾尚无可行闭环。禁止把未回复、沉默或检查通过记为用户确认。
+
 ---
 
 ## 新项目 Checklist（Stage 4 完成判定）

skills/engineering-automation-playbooks/references/checklists.md

@@ -68,9 +68,17 @@ npm run build
 
 ## 需求文档完备性 Checklist（Stage 1 用）
 
-> Agent 收到用户给的需求文档后，按这套清单校验。**全过才进 Stage 2**。
+> Agent 收到需求材料或被要求审查需求时，先查证、再审查、提出建议，等待用户确认后推进。`PASS` 只表示需求覆盖充分；进入下一阶段还须有用户对结论、取舍和下一步的明确确认。
 
-### 必须项（任何一项缺失 → 退回用户补）
+### 审查顺序
+
+1. 从用户材料和相关已有文档中提取目标、角色、场景、范围与约束，记录来源。文档冲突或无法查证时标明不确定性；业务意图由用户确认。
+2. 沿主流程检查触发、处理、交接和完成条件，核对范围、业务规则与验收是否一致。跨角色、审批或集成场景按需检查权限、状态流转和数据来源；关注重复提交、驳回、超时、无权限等与本需求相关的异常。
+3. 将缺口分为“必须先解决”和“可后置”。缺口会改变核心流程、范围、权限、数据口径或完成判定时须先解决；可后置项须说明适用边界、影响及关闭时点，由用户确认后置。
+4. 每个关键缺口写明证据、影响、可选方案、代价和推荐理由。依据不足时给出验证路径；建议保持待确认状态，禁止补写未确认规则或扩大范围。
+5. 汇总需要用户确认的需求理解、业务规则、范围取舍和下一步。未确认前继续停留在查证与审查；部分答复仅关闭对应事项，已有明确确认不重复索取。
+
+### 必须项（缺失 → 先查证，再带影响与建议请用户确认）
 
 - [ ] 业务背景：能解释"为什么做"
 - [ ] 目标用户：至少 1 类用户的场景与痛点
@@ -80,14 +88,17 @@ npm run build
 - [ ] 非目标：明确这一版不做什么
 - [ ] 关键约束：合规 / 性能 / 时间 / 预算 至少一项明确
 - [ ] Owner：可对接的负责人
+- [ ] 业务闭环：触发、处理、交接和完成条件明确，P0 能独立完成核心任务
+- [ ] 规则与验收：关键规则和相关异常都有可观察的预期结果
+- [ ] 场景适用项：涉及权限、审批、状态流转、数据口径或集成时，相关边界和依赖明确；不适用项说明原因
 
 ### 应有项（缺失但可推迟）
 
 - [ ] P1 / Later 列表
 - [ ] 已知风险
 - [ ] 与现有系统的关系
 
-### 危险信号（命中任一 → 立即提问，不要往下做）
+### 危险信号（命中任一 → 查证并解释影响，提出建议，等待用户决策）
 
 - [ ] 出现"差不多就行 / 你看着办 / 行业标准"等模糊词，且不肯具体化
 - [ ] 验收标准全是主观词（好用、流畅、漂亮）
@@ -96,17 +107,23 @@ npm run build
 - [ ] 成功指标不可量化或无截止时间
 - [ ] 性能/合规约束与所选架构明显冲突
 - [ ] 只有功能愿望，没有 Persona / Scenario / Pain 的证据
+- [ ] 角色权限、状态流转或验收与业务规则互相矛盾
+- [ ] 用拆分 MVP 删除了完成核心任务必需的规则、权限或异常处理
 
 ### Agent 输出格式
 
 ```text
 需求文档完备性: <PASS | NEEDS-USER-INPUT | BLOCKED>
-缺失必须项: <逐条列出>
-建议补充项: <逐条列出>
-需用户回答的问题: <编号列表>
-可继续推进的部分: <如可先做架构选型部分>
+需求理解: <目标、角色/场景、核心流程、本期范围；注明来源及待确认假设>
+缺失必须项: <逐项列出证据、影响、可选方案/代价、推荐理由>
+建议补充项: <可后置问题、影响、建议边界及关闭时点>
+需用户确认的事项: <编号列出理解、规则、范围取舍和下一步>
+确认状态: <待确认 | 部分确认 | 已确认；关联用户实际确认的事项与需求版本>
+可继续推进的部分: <未确认时仅查证和完善审查；确认后按约定范围推进>
 ```
 
+`NEEDS-USER-INPUT` 表示关键业务信息或决策待确认；`BLOCKED` 表示核心矛盾尚无可行闭环。禁止把未回复、沉默或检查通过记为用户确认。
+
 ---
 
 ## 新项目 Checklist（Stage 4 完成判定）