From 6f47c919addd348414c3f02f4931a50b59e63bb0 Mon Sep 17 00:00:00 2001 From: Haodi Fan Date: Thu, 1 Oct 2026 02:57:47 +0800 Subject: [PATCH] feat: review requirements before user-confirmed handoff Closes #21. Add evidence-based gap analysis, recommendations, and separate confirmation status; sync managed references and document validation. --- ...6-10-01-requirement-review-confirmation.md | 49 +++++++++++++++++++ references/checklists.md | 31 +++++++++--- references/templates-specs.md | 34 ++++++++++--- .../references/checklists.md | 31 +++++++++--- .../references/checklists.md | 31 +++++++++--- .../references/checklists.md | 31 +++++++++--- .../references/checklists.md | 31 +++++++++--- .../references/checklists.md | 31 +++++++++--- .../references/templates-specs.md | 34 ++++++++++--- .../engineering-product-definition/SKILL.md | 19 ++++--- .../references/checklists.md | 31 +++++++++--- .../references/templates-specs.md | 34 ++++++++++--- .../references/checklists.md | 31 +++++++++--- .../references/checklists.md | 31 +++++++++--- 14 files changed, 360 insertions(+), 89 deletions(-) create mode 100644 docs/design/active/2026-10-01-requirement-review-confirmation.md diff --git a/docs/design/active/2026-10-01-requirement-review-confirmation.md b/docs/design/active/2026-10-01-requirement-review-confirmation.md new file mode 100644 index 0000000..bb0c725 --- /dev/null +++ b/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 链接与验证依据。 diff --git a/references/checklists.md b/references/checklists.md index bd60293..8672b7c 100644 --- a/references/checklists.md +++ b/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,6 +88,9 @@ npm run build - [ ] 非目标：明确这一版不做什么 - [ ] 关键约束：合规 / 性能 / 时间 / 预算 至少一项明确 - [ ] Owner：可对接的负责人 +- [ ] 业务闭环：触发、处理、交接和完成条件明确，P0 能独立完成核心任务 +- [ ] 规则与验收：关键规则和相关异常都有可观察的预期结果 +- [ ] 场景适用项：涉及权限、审批、状态流转、数据口径或集成时，相关边界和依赖明确；不适用项说明原因 ### 应有项（缺失但可推迟） @@ -87,7 +98,7 @@ npm run build - [ ] 已知风险 - [ ] 与现有系统的关系 -### 危险信号（命中任一 → 立即提问，不要往下做） +### 危险信号（命中任一 → 查证并解释影响，提出建议，等待用户决策） - [ ] 出现"差不多就行 / 你看着办 / 行业标准"等模糊词，且不肯具体化 - [ ] 验收标准全是主观词（好用、流畅、漂亮） @@ -96,17 +107,23 @@ npm run build - [ ] 成功指标不可量化或无截止时间 - [ ] 性能/合规约束与所选架构明显冲突 - [ ] 只有功能愿望，没有 Persona / Scenario / Pain 的证据 +- [ ] 角色权限、状态流转或验收与业务规则互相矛盾 +- [ ] 用拆分 MVP 删除了完成核心任务必需的规则、权限或异常处理 ### Agent 输出格式 ```text 需求文档完备性: -缺失必须项: <逐条列出> -建议补充项: <逐条列出> -需用户回答的问题: <编号列表> -可继续推进的部分: <如可先做架构选型部分> +需求理解: <目标、角色/场景、核心流程、本期范围；注明来源及待确认假设> +缺失必须项: <逐项列出证据、影响、可选方案/代价、推荐理由> +建议补充项: <可后置问题、影响、建议边界及关闭时点> +需用户确认的事项: <编号列出理解、规则、范围取舍和下一步> +确认状态: <待确认 | 部分确认 | 已确认；关联用户实际确认的事项与需求版本> +可继续推进的部分: <未确认时仅查证和完善审查；确认后按约定范围推进> ``` +`NEEDS-USER-INPUT` 表示关键业务信息或决策待确认；`BLOCKED` 表示核心矛盾尚无可行闭环。禁止把未回复、沉默或检查通过记为用户确认。 + --- ## 新项目 Checklist（Stage 4 完成判定） diff --git a/references/templates-specs.md b/references/templates-specs.md index 41d9f01..a457145 100644 --- a/references/templates-specs.md +++ b/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: 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 diff --git a/skills/engineering-architecture-design/references/checklists.md b/skills/engineering-architecture-design/references/checklists.md index bd60293..8672b7c 100644 --- a/skills/engineering-architecture-design/references/checklists.md +++ b/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,6 +88,9 @@ npm run build - [ ] 非目标：明确这一版不做什么 - [ ] 关键约束：合规 / 性能 / 时间 / 预算 至少一项明确 - [ ] Owner：可对接的负责人 +- [ ] 业务闭环：触发、处理、交接和完成条件明确，P0 能独立完成核心任务 +- [ ] 规则与验收：关键规则和相关异常都有可观察的预期结果 +- [ ] 场景适用项：涉及权限、审批、状态流转、数据口径或集成时，相关边界和依赖明确；不适用项说明原因 ### 应有项（缺失但可推迟） @@ -87,7 +98,7 @@ npm run build - [ ] 已知风险 - [ ] 与现有系统的关系 -### 危险信号（命中任一 → 立即提问，不要往下做） +### 危险信号（命中任一 → 查证并解释影响，提出建议，等待用户决策） - [ ] 出现"差不多就行 / 你看着办 / 行业标准"等模糊词，且不肯具体化 - [ ] 验收标准全是主观词（好用、流畅、漂亮） @@ -96,17 +107,23 @@ npm run build - [ ] 成功指标不可量化或无截止时间 - [ ] 性能/合规约束与所选架构明显冲突 - [ ] 只有功能愿望，没有 Persona / Scenario / Pain 的证据 +- [ ] 角色权限、状态流转或验收与业务规则互相矛盾 +- [ ] 用拆分 MVP 删除了完成核心任务必需的规则、权限或异常处理 ### Agent 输出格式 ```text 需求文档完备性: -缺失必须项: <逐条列出> -建议补充项: <逐条列出> -需用户回答的问题: <编号列表> -可继续推进的部分: <如可先做架构选型部分> +需求理解: <目标、角色/场景、核心流程、本期范围；注明来源及待确认假设> +缺失必须项: <逐项列出证据、影响、可选方案/代价、推荐理由> +建议补充项: <可后置问题、影响、建议边界及关闭时点> +需用户确认的事项: <编号列出理解、规则、范围取舍和下一步> +确认状态: <待确认 | 部分确认 | 已确认；关联用户实际确认的事项与需求版本> +可继续推进的部分: <未确认时仅查证和完善审查；确认后按约定范围推进> ``` +`NEEDS-USER-INPUT` 表示关键业务信息或决策待确认；`BLOCKED` 表示核心矛盾尚无可行闭环。禁止把未回复、沉默或检查通过记为用户确认。 + --- ## 新项目 Checklist（Stage 4 完成判定） diff --git a/skills/engineering-automation-playbooks/references/checklists.md b/skills/engineering-automation-playbooks/references/checklists.md index bd60293..8672b7c 100644 --- a/skills/engineering-automation-playbooks/references/checklists.md +++ b/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,6 +88,9 @@ npm run build - [ ] 非目标：明确这一版不做什么 - [ ] 关键约束：合规 / 性能 / 时间 / 预算 至少一项明确 - [ ] Owner：可对接的负责人 +- [ ] 业务闭环：触发、处理、交接和完成条件明确，P0 能独立完成核心任务 +- [ ] 规则与验收：关键规则和相关异常都有可观察的预期结果 +- [ ] 场景适用项：涉及权限、审批、状态流转、数据口径或集成时，相关边界和依赖明确；不适用项说明原因 ### 应有项（缺失但可推迟） @@ -87,7 +98,7 @@ npm run build - [ ] 已知风险 - [ ] 与现有系统的关系 -### 危险信号（命中任一 → 立即提问，不要往下做） +### 危险信号（命中任一 → 查证并解释影响，提出建议，等待用户决策） - [ ] 出现"差不多就行 / 你看着办 / 行业标准"等模糊词，且不肯具体化 - [ ] 验收标准全是主观词（好用、流畅、漂亮） @@ -96,17 +107,23 @@ npm run build - [ ] 成功指标不可量化或无截止时间 - [ ] 性能/合规约束与所选架构明显冲突 - [ ] 只有功能愿望，没有 Persona / Scenario / Pain 的证据 +- [ ] 角色权限、状态流转或验收与业务规则互相矛盾 +- [ ] 用拆分 MVP 删除了完成核心任务必需的规则、权限或异常处理 ### Agent 输出格式 ```text 需求文档完备性: -缺失必须项: <逐条列出> -建议补充项: <逐条列出> -需用户回答的问题: <编号列表> -可继续推进的部分: <如可先做架构选型部分> +需求理解: <目标、角色/场景、核心流程、本期范围；注明来源及待确认假设> +缺失必须项: <逐项列出证据、影响、可选方案/代价、推荐理由> +建议补充项: <可后置问题、影响、建议边界及关闭时点> +需用户确认的事项: <编号列出理解、规则、范围取舍和下一步> +确认状态: <待确认 | 部分确认 | 已确认；关联用户实际确认的事项与需求版本> +可继续推进的部分: <未确认时仅查证和完善审查；确认后按约定范围推进> ``` +`NEEDS-USER-INPUT` 表示关键业务信息或决策待确认；`BLOCKED` 表示核心矛盾尚无可行闭环。禁止把未回复、沉默或检查通过记为用户确认。 + --- ## 新项目 Checklist（Stage 4 完成判定） diff --git a/skills/engineering-build-verify/references/checklists.md b/skills/engineering-build-verify/references/checklists.md index bd60293..8672b7c 100644 --- a/skills/engineering-build-verify/references/checklists.md +++ b/skills/engineering-build-verify/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,6 +88,9 @@ npm run build - [ ] 非目标：明确这一版不做什么 - [ ] 关键约束：合规 / 性能 / 时间 / 预算 至少一项明确 - [ ] Owner：可对接的负责人 +- [ ] 业务闭环：触发、处理、交接和完成条件明确，P0 能独立完成核心任务 +- [ ] 规则与验收：关键规则和相关异常都有可观察的预期结果 +- [ ] 场景适用项：涉及权限、审批、状态流转、数据口径或集成时，相关边界和依赖明确；不适用项说明原因 ### 应有项（缺失但可推迟） @@ -87,7 +98,7 @@ npm run build - [ ] 已知风险 - [ ] 与现有系统的关系 -### 危险信号（命中任一 → 立即提问，不要往下做） +### 危险信号（命中任一 → 查证并解释影响，提出建议，等待用户决策） - [ ] 出现"差不多就行 / 你看着办 / 行业标准"等模糊词，且不肯具体化 - [ ] 验收标准全是主观词（好用、流畅、漂亮） @@ -96,17 +107,23 @@ npm run build - [ ] 成功指标不可量化或无截止时间 - [ ] 性能/合规约束与所选架构明显冲突 - [ ] 只有功能愿望，没有 Persona / Scenario / Pain 的证据 +- [ ] 角色权限、状态流转或验收与业务规则互相矛盾 +- [ ] 用拆分 MVP 删除了完成核心任务必需的规则、权限或异常处理 ### Agent 输出格式 ```text 需求文档完备性: -缺失必须项: <逐条列出> -建议补充项: <逐条列出> -需用户回答的问题: <编号列表> -可继续推进的部分: <如可先做架构选型部分> +需求理解: <目标、角色/场景、核心流程、本期范围；注明来源及待确认假设> +缺失必须项: <逐项列出证据、影响、可选方案/代价、推荐理由> +建议补充项: <可后置问题、影响、建议边界及关闭时点> +需用户确认的事项: <编号列出理解、规则、范围取舍和下一步> +确认状态: <待确认 | 部分确认 | 已确认；关联用户实际确认的事项与需求版本> +可继续推进的部分: <未确认时仅查证和完善审查；确认后按约定范围推进> ``` +`NEEDS-USER-INPUT` 表示关键业务信息或决策待确认；`BLOCKED` 表示核心矛盾尚无可行闭环。禁止把未回复、沉默或检查通过记为用户确认。 + --- ## 新项目 Checklist（Stage 4 完成判定） diff --git a/skills/engineering-execution-planning/references/checklists.md b/skills/engineering-execution-planning/references/checklists.md index bd60293..8672b7c 100644 --- a/skills/engineering-execution-planning/references/checklists.md +++ b/skills/engineering-execution-planning/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,6 +88,9 @@ npm run build - [ ] 非目标：明确这一版不做什么 - [ ] 关键约束：合规 / 性能 / 时间 / 预算 至少一项明确 - [ ] Owner：可对接的负责人 +- [ ] 业务闭环：触发、处理、交接和完成条件明确，P0 能独立完成核心任务 +- [ ] 规则与验收：关键规则和相关异常都有可观察的预期结果 +- [ ] 场景适用项：涉及权限、审批、状态流转、数据口径或集成时，相关边界和依赖明确；不适用项说明原因 ### 应有项（缺失但可推迟） @@ -87,7 +98,7 @@ npm run build - [ ] 已知风险 - [ ] 与现有系统的关系 -### 危险信号（命中任一 → 立即提问，不要往下做） +### 危险信号（命中任一 → 查证并解释影响，提出建议，等待用户决策） - [ ] 出现"差不多就行 / 你看着办 / 行业标准"等模糊词，且不肯具体化 - [ ] 验收标准全是主观词（好用、流畅、漂亮） @@ -96,17 +107,23 @@ npm run build - [ ] 成功指标不可量化或无截止时间 - [ ] 性能/合规约束与所选架构明显冲突 - [ ] 只有功能愿望，没有 Persona / Scenario / Pain 的证据 +- [ ] 角色权限、状态流转或验收与业务规则互相矛盾 +- [ ] 用拆分 MVP 删除了完成核心任务必需的规则、权限或异常处理 ### Agent 输出格式 ```text 需求文档完备性: -缺失必须项: <逐条列出> -建议补充项: <逐条列出> -需用户回答的问题: <编号列表> -可继续推进的部分: <如可先做架构选型部分> +需求理解: <目标、角色/场景、核心流程、本期范围；注明来源及待确认假设> +缺失必须项: <逐项列出证据、影响、可选方案/代价、推荐理由> +建议补充项: <可后置问题、影响、建议边界及关闭时点> +需用户确认的事项: <编号列出理解、规则、范围取舍和下一步> +确认状态: <待确认 | 部分确认 | 已确认；关联用户实际确认的事项与需求版本> +可继续推进的部分: <未确认时仅查证和完善审查；确认后按约定范围推进> ``` +`NEEDS-USER-INPUT` 表示关键业务信息或决策待确认；`BLOCKED` 表示核心矛盾尚无可行闭环。禁止把未回复、沉默或检查通过记为用户确认。 + --- ## 新项目 Checklist（Stage 4 完成判定） diff --git a/skills/engineering-organization-systems/references/checklists.md b/skills/engineering-organization-systems/references/checklists.md index bd60293..8672b7c 100644 --- a/skills/engineering-organization-systems/references/checklists.md +++ b/skills/engineering-organization-systems/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,6 +88,9 @@ npm run build - [ ] 非目标：明确这一版不做什么 - [ ] 关键约束：合规 / 性能 / 时间 / 预算 至少一项明确 - [ ] Owner：可对接的负责人 +- [ ] 业务闭环：触发、处理、交接和完成条件明确，P0 能独立完成核心任务 +- [ ] 规则与验收：关键规则和相关异常都有可观察的预期结果 +- [ ] 场景适用项：涉及权限、审批、状态流转、数据口径或集成时，相关边界和依赖明确；不适用项说明原因 ### 应有项（缺失但可推迟） @@ -87,7 +98,7 @@ npm run build - [ ] 已知风险 - [ ] 与现有系统的关系 -### 危险信号（命中任一 → 立即提问，不要往下做） +### 危险信号（命中任一 → 查证并解释影响，提出建议，等待用户决策） - [ ] 出现"差不多就行 / 你看着办 / 行业标准"等模糊词，且不肯具体化 - [ ] 验收标准全是主观词（好用、流畅、漂亮） @@ -96,17 +107,23 @@ npm run build - [ ] 成功指标不可量化或无截止时间 - [ ] 性能/合规约束与所选架构明显冲突 - [ ] 只有功能愿望，没有 Persona / Scenario / Pain 的证据 +- [ ] 角色权限、状态流转或验收与业务规则互相矛盾 +- [ ] 用拆分 MVP 删除了完成核心任务必需的规则、权限或异常处理 ### Agent 输出格式 ```text 需求文档完备性: -缺失必须项: <逐条列出> -建议补充项: <逐条列出> -需用户回答的问题: <编号列表> -可继续推进的部分: <如可先做架构选型部分> +需求理解: <目标、角色/场景、核心流程、本期范围；注明来源及待确认假设> +缺失必须项: <逐项列出证据、影响、可选方案/代价、推荐理由> +建议补充项: <可后置问题、影响、建议边界及关闭时点> +需用户确认的事项: <编号列出理解、规则、范围取舍和下一步> +确认状态: <待确认 | 部分确认 | 已确认；关联用户实际确认的事项与需求版本> +可继续推进的部分: <未确认时仅查证和完善审查；确认后按约定范围推进> ``` +`NEEDS-USER-INPUT` 表示关键业务信息或决策待确认；`BLOCKED` 表示核心矛盾尚无可行闭环。禁止把未回复、沉默或检查通过记为用户确认。 + --- ## 新项目 Checklist（Stage 4 完成判定） diff --git a/skills/engineering-organization-systems/references/templates-specs.md b/skills/engineering-organization-systems/references/templates-specs.md index 41d9f01..a457145 100644 --- a/skills/engineering-organization-systems/references/templates-specs.md +++ b/skills/engineering-organization-systems/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: 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 diff --git a/skills/engineering-product-definition/SKILL.md b/skills/engineering-product-definition/SKILL.md index 7e1c327..5f9f00f 100644 --- a/skills/engineering-product-definition/SKILL.md +++ b/skills/engineering-product-definition/SKILL.md @@ -1,30 +1,32 @@ --- name: engineering-product-definition -description: Use when clarifying a product idea, PRD, requirements, PSPS, user scenario, scope, non-goals, or success criteria before architecture or implementation. +description: Use when clarifying or reviewing a product idea, PRD, requirements, PSPS, user scenario, scope, non-goals, or success criteria, finding gaps and recommending decisions for user confirmation before architecture or implementation. metadata: version: 0.13.0 --- # Engineering Product Definition / 产品定义 -把模糊想法变成可构建、可验证、可拒绝扩张的需求边界。业务意图必须来自用户或 owner；agent 负责结构化、校验和追问。 +把模糊想法变成可构建、可验证、可拒绝扩张的需求边界。业务意图必须来自用户或 owner；agent 负责查证、结构化、审查和建议，业务取舍由用户确认。 ## 何时使用 -- 用户说“我有个想法”“帮我写 PRD”“需求怎么定义”“PSPS”“用户场景不清楚”。 +- 用户说“我有个想法”“帮我写 PRD”“需求怎么定义”“审需求”“需求评审”“检查 PRD”“PSPS”“用户场景不清楚”。 - 当前还没有可执行 spec、成功指标、非目标或验收标准。 - 架构、实现、排期依赖业务边界先清楚。 ## 工作流 -1. 明确一句话定义：用户、系统类型、核心能力、核心问题、P0 非目标。 -2. 抽取 PSPS：Persona、Scenario、Pain、Solution Surface。 -3. 区分事实、假设、待用户回答；不要用合理想象填业务需求。 -4. 给出 P0/P1/P2 范围，P0 必须能形成最小闭环。 -5. 只有需求完备性足够时，才进入 design doc、架构或实现。 +1. 先读取用户材料和相关已有文档，查清可查证的事实，提取一句话定义与 PSPS；已有内容直接引用，缺失项标明，避免交给用户一份空白清单。 +2. 按 `references/checklists.md` 的需求审查流程检查业务闭环、范围、规则与异常、约束和验收。区分事实、假设、建议与待决事项，不把推测写成已确认需求。 +3. 分级说明缺口及影响。涉及业务取舍时给出可选方案、代价和推荐理由；提出 P0/P1/P2 范围建议，P0 必须保住最小业务闭环。 +4. 输出需求理解、关键缺口、建议和需用户确认的事项，等待用户明确确认审查结论及取舍。完备性检查通过本身不构成推进授权；用户只回答部分问题时，继续标明未决项。 +5. 用户确认后，将已确认内容更新到需求文档，再进入约定的下一步。已确认决策直接沿用，只有新增关键假设或范围变化才重新确认。 ## 输出模板 +需求审查结果使用 `references/checklists.md` 的 Agent 输出格式；规划 / 路由输出继续使用以下字段。 + ```text 工程路由: Product | 产品定义 | Product 当前阶段: 0 想法 / 1 需求澄清 / 2 Spec @@ -45,6 +47,7 @@ metadata: - 缺少业务 owner、目标用户、核心流程或成功指标，且错误假设代价高。 - 用户要求 agent 编造业务需求，而不是结构化已知事实。 - P0 范围无法形成可验收闭环。 +- 审查结论或业务取舍尚未得到用户明确确认；此时可继续查证和完善建议，保持在需求审查阶段。 ## References diff --git a/skills/engineering-product-definition/references/checklists.md b/skills/engineering-product-definition/references/checklists.md index bd60293..8672b7c 100644 --- a/skills/engineering-product-definition/references/checklists.md +++ b/skills/engineering-product-definition/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,6 +88,9 @@ npm run build - [ ] 非目标：明确这一版不做什么 - [ ] 关键约束：合规 / 性能 / 时间 / 预算 至少一项明确 - [ ] Owner：可对接的负责人 +- [ ] 业务闭环：触发、处理、交接和完成条件明确，P0 能独立完成核心任务 +- [ ] 规则与验收：关键规则和相关异常都有可观察的预期结果 +- [ ] 场景适用项：涉及权限、审批、状态流转、数据口径或集成时，相关边界和依赖明确；不适用项说明原因 ### 应有项（缺失但可推迟） @@ -87,7 +98,7 @@ npm run build - [ ] 已知风险 - [ ] 与现有系统的关系 -### 危险信号（命中任一 → 立即提问，不要往下做） +### 危险信号（命中任一 → 查证并解释影响，提出建议，等待用户决策） - [ ] 出现"差不多就行 / 你看着办 / 行业标准"等模糊词，且不肯具体化 - [ ] 验收标准全是主观词（好用、流畅、漂亮） @@ -96,17 +107,23 @@ npm run build - [ ] 成功指标不可量化或无截止时间 - [ ] 性能/合规约束与所选架构明显冲突 - [ ] 只有功能愿望，没有 Persona / Scenario / Pain 的证据 +- [ ] 角色权限、状态流转或验收与业务规则互相矛盾 +- [ ] 用拆分 MVP 删除了完成核心任务必需的规则、权限或异常处理 ### Agent 输出格式 ```text 需求文档完备性: -缺失必须项: <逐条列出> -建议补充项: <逐条列出> -需用户回答的问题: <编号列表> -可继续推进的部分: <如可先做架构选型部分> +需求理解: <目标、角色/场景、核心流程、本期范围；注明来源及待确认假设> +缺失必须项: <逐项列出证据、影响、可选方案/代价、推荐理由> +建议补充项: <可后置问题、影响、建议边界及关闭时点> +需用户确认的事项: <编号列出理解、规则、范围取舍和下一步> +确认状态: <待确认 | 部分确认 | 已确认；关联用户实际确认的事项与需求版本> +可继续推进的部分: <未确认时仅查证和完善审查；确认后按约定范围推进> ``` +`NEEDS-USER-INPUT` 表示关键业务信息或决策待确认；`BLOCKED` 表示核心矛盾尚无可行闭环。禁止把未回复、沉默或检查通过记为用户确认。 + --- ## 新项目 Checklist（Stage 4 完成判定） diff --git a/skills/engineering-product-definition/references/templates-specs.md b/skills/engineering-product-definition/references/templates-specs.md index 41d9f01..a457145 100644 --- a/skills/engineering-product-definition/references/templates-specs.md +++ b/skills/engineering-product-definition/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: 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 diff --git a/skills/engineering-refactoring/references/checklists.md b/skills/engineering-refactoring/references/checklists.md index bd60293..8672b7c 100644 --- a/skills/engineering-refactoring/references/checklists.md +++ b/skills/engineering-refactoring/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,6 +88,9 @@ npm run build - [ ] 非目标：明确这一版不做什么 - [ ] 关键约束：合规 / 性能 / 时间 / 预算 至少一项明确 - [ ] Owner：可对接的负责人 +- [ ] 业务闭环：触发、处理、交接和完成条件明确，P0 能独立完成核心任务 +- [ ] 规则与验收：关键规则和相关异常都有可观察的预期结果 +- [ ] 场景适用项：涉及权限、审批、状态流转、数据口径或集成时，相关边界和依赖明确；不适用项说明原因 ### 应有项（缺失但可推迟） @@ -87,7 +98,7 @@ npm run build - [ ] 已知风险 - [ ] 与现有系统的关系 -### 危险信号（命中任一 → 立即提问，不要往下做） +### 危险信号（命中任一 → 查证并解释影响，提出建议，等待用户决策） - [ ] 出现"差不多就行 / 你看着办 / 行业标准"等模糊词，且不肯具体化 - [ ] 验收标准全是主观词（好用、流畅、漂亮） @@ -96,17 +107,23 @@ npm run build - [ ] 成功指标不可量化或无截止时间 - [ ] 性能/合规约束与所选架构明显冲突 - [ ] 只有功能愿望，没有 Persona / Scenario / Pain 的证据 +- [ ] 角色权限、状态流转或验收与业务规则互相矛盾 +- [ ] 用拆分 MVP 删除了完成核心任务必需的规则、权限或异常处理 ### Agent 输出格式 ```text 需求文档完备性: -缺失必须项: <逐条列出> -建议补充项: <逐条列出> -需用户回答的问题: <编号列表> -可继续推进的部分: <如可先做架构选型部分> +需求理解: <目标、角色/场景、核心流程、本期范围；注明来源及待确认假设> +缺失必须项: <逐项列出证据、影响、可选方案/代价、推荐理由> +建议补充项: <可后置问题、影响、建议边界及关闭时点> +需用户确认的事项: <编号列出理解、规则、范围取舍和下一步> +确认状态: <待确认 | 部分确认 | 已确认；关联用户实际确认的事项与需求版本> +可继续推进的部分: <未确认时仅查证和完善审查；确认后按约定范围推进> ``` +`NEEDS-USER-INPUT` 表示关键业务信息或决策待确认；`BLOCKED` 表示核心矛盾尚无可行闭环。禁止把未回复、沉默或检查通过记为用户确认。 + --- ## 新项目 Checklist（Stage 4 完成判定） diff --git a/skills/engineering-review-release/references/checklists.md b/skills/engineering-review-release/references/checklists.md index bd60293..8672b7c 100644 --- a/skills/engineering-review-release/references/checklists.md +++ b/skills/engineering-review-release/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,6 +88,9 @@ npm run build - [ ] 非目标：明确这一版不做什么 - [ ] 关键约束：合规 / 性能 / 时间 / 预算 至少一项明确 - [ ] Owner：可对接的负责人 +- [ ] 业务闭环：触发、处理、交接和完成条件明确，P0 能独立完成核心任务 +- [ ] 规则与验收：关键规则和相关异常都有可观察的预期结果 +- [ ] 场景适用项：涉及权限、审批、状态流转、数据口径或集成时，相关边界和依赖明确；不适用项说明原因 ### 应有项（缺失但可推迟） @@ -87,7 +98,7 @@ npm run build - [ ] 已知风险 - [ ] 与现有系统的关系 -### 危险信号（命中任一 → 立即提问，不要往下做） +### 危险信号（命中任一 → 查证并解释影响，提出建议，等待用户决策） - [ ] 出现"差不多就行 / 你看着办 / 行业标准"等模糊词，且不肯具体化 - [ ] 验收标准全是主观词（好用、流畅、漂亮） @@ -96,17 +107,23 @@ npm run build - [ ] 成功指标不可量化或无截止时间 - [ ] 性能/合规约束与所选架构明显冲突 - [ ] 只有功能愿望，没有 Persona / Scenario / Pain 的证据 +- [ ] 角色权限、状态流转或验收与业务规则互相矛盾 +- [ ] 用拆分 MVP 删除了完成核心任务必需的规则、权限或异常处理 ### Agent 输出格式 ```text 需求文档完备性: -缺失必须项: <逐条列出> -建议补充项: <逐条列出> -需用户回答的问题: <编号列表> -可继续推进的部分: <如可先做架构选型部分> +需求理解: <目标、角色/场景、核心流程、本期范围；注明来源及待确认假设> +缺失必须项: <逐项列出证据、影响、可选方案/代价、推荐理由> +建议补充项: <可后置问题、影响、建议边界及关闭时点> +需用户确认的事项: <编号列出理解、规则、范围取舍和下一步> +确认状态: <待确认 | 部分确认 | 已确认；关联用户实际确认的事项与需求版本> +可继续推进的部分: <未确认时仅查证和完善审查；确认后按约定范围推进> ``` +`NEEDS-USER-INPUT` 表示关键业务信息或决策待确认；`BLOCKED` 表示核心矛盾尚无可行闭环。禁止把未回复、沉默或检查通过记为用户确认。 + --- ## 新项目 Checklist（Stage 4 完成判定）