--- name: product-clarification description: 从需求文档、原型和相关项目事实中识别产品材料缺失、业务口径冲突与开发前待确认事项，按配套 HTML 模板生成可填写的产品确认清单，并核对填写结果以完善需求总结。挂载于 DSH 需求分析元技能。 whenToUse: 需求文档或原型存在缺项、歧义、冲突，或有影响实现范围和验收的业务决策需要产品确认时使用；已有明确答复的事项不重复征询。 --- # 产品待确认清单 把尚不能确定的业务问题整理成产品能独立阅读、填写并交回的确认清单。最终交付使用 [HTML 基线模板](assets/confirmation-checklist-v1.html)，保留其版式、选项、自由填写、自动保存与 JSON 导出交互。 本文的资源路径均相对于本 Skill 目录。按当前加载引用定位实际安装位置：项目级通常为 `.dsh/skills/product-clarification/`，Codex 项目来源为 `.agents/skills/product-clarification/`，用户级以宿主的 Skill 目录为准（通常是 `DSH_HOME/skills/`，未设置时为 `~/.dsh/skills/`）。不要把业务项目的当前目录误当作 Skill 目录。 ## 先找真正需要确认的问题 读取当前需求文档、可访问的原型及用户指定材料。先记清哪些材料已经查阅、哪些未提供或无法访问；只围绕当前需求查阅必要的项目事实，不要求全仓扫描。 优先核对目标和本期范围、业务对象与字段含义、角色和可见范围、流程及状态结果、校验与边界、异常处理、历史数据及验收口径。按实际功能选取相关维度，不把这份检查方向原样变成固定问卷。 - 文档或原型已经明确的内容直接引用；现有实现能说明“当前怎样”，不能替产品决定“本次应怎样”。 - 有缺失、互相冲突或多种合理解释，且会改变实现或验收结果时，才列为待确认项。不要为了凑数量制造问题。 - 未提供的材料如实写“未提供／无法核对”；只有影响当前决策的缺失才要求补充，并指出需要哪一部分。 - 同一决定合并提问；每题聚焦一个业务决定，用具体场景、输入和可观察结果表达。避免只问“是否考虑权限”“异常怎么处理”等泛问。 - 面向产品确认业务口径，不让产品替开发选择数据库表、类名或实现框架。纯技术问题留给开发／技术负责人，交接时单独说明；若技术约束影响业务选择，先解释业务影响。 ## 编成可填写的清单 生成数据前读取 [数据约定](references/checklist-data.md)。清单标题和文件名标明本轮版本，避免与模板版本 V1.0 混淆。每题填写：问题类型、具体问题、查到的依据或材料缺口、需要决定的事项。依据要能定位到文档章节、原型页面或真实文件位置；找不到依据时不得编造引用。 有可比较的业务方案时提供清楚、平衡的选项；有合理建议时明确它是“建议，待产品确认”。信息不足时保留自由填写，不强行给建议。选项和建议不能预先当成已确认答案。模板自带“自己填写”，不必重复添加。 只替换模板的 `#card-data` JSON，不重写模板的 CSS、页面结构和交互脚本，也不要保留模板原有的示例题。 若当前 `dev_task` 提供 `write_requirement_material`，优先使用它，在需求确认前直接生成材料，不需要终端命令。参数如下： - `material_name`：如 `product/待产品确认-v1.html`，相对于工具返回的任务材料目录。 - `material_template.skill_name`：当前实际加载的完整引用，如 `user:product-clarification`，以当前挂载来源为准。 - `material_template.path`：`assets/confirmation-checklist-v1.html`。 - `material_template.data_id`：`card-data`。 - `material_template.json`：JSON 字符串，包含 `engine_task_id`（当前任务标识）、`revision`、`title`、`questions`，问题结构沿用数据约定。此路径不填写脚本专用的 `checklist_hash`。 - `material_template.identity_field`：`task_id`。由插件填入随内容变化的清单标识，隔离不同版本的缓存。 向开发交付工具实际返回的 `material.path`。不要把“材料生成成功”记录成产品已确认。已登记材料修改需要当前指纹；遇到人工修改保留原稿，用新版本文件名生成。旧材料不再作为本期依据时，可用 `retire_requirement_material` 及当前材料指纹停用登记，原文件会保留。 在允许执行脚本的其他上下文，也可使用配套生成器： ```text node <本 Skill 目录>/scripts/checklist.mjs render --data <清单数据.json> --output <待产品确认.html> ``` 脚本同样会生成随问题内容变化的清单标识。输出存在且内容不同时会停止，改用新版本文件名保留旧稿。 使用当前宿主允许的文件写入／导出能力保存材料；仅在允许执行脚本时运行上面的命令。输出位置遵循用户约定，未约定时使用 `docs/requirements/<任务标识>/`。完成后给开发 HTML 文件路径、待确认项数及关键阻塞事项，说明产品可在浏览器填写后导出 `01-确认结果.json` 交回。 若没有实际待确认项，说明已核对的依据即可，不生成空问卷。若宿主限制文件写入和命令，交付问题正文及清单数据，明确 HTML 尚未保存；需要宿主提供材料写入能力后继续。Skill 本身不授予工具权限，不能为解锁写入而提前确认需求或切换任务绕过门禁。 ## 产品填回后 以对应版本的 HTML 和产品交回的 JSON 核对结果。读取 HTML 的 `#card-data` 数据和返回 JSON，按下述规则比对即可，不要求在需求阶段执行命令。允许执行脚本时可使用： ```text node <本 Skill 目录>/scripts/checklist.mjs check-answers --checklist <本版待产品确认.html> --answers <01-确认结果.json> ``` 核对清单标识、题目数量、序号、类型和题目正文，防止混入旧版或其他任务的答复。以 `answer` 的最终文字为准，不能用选项名称替代产品改写后的答案。脚本仅校验结构与版本对应关系，不证明答复人身份或业务口径已经完整。 再检查答复是否具体、是否仍有“待定／按正常逻辑”等模糊表述、是否互相矛盾或引入新范围。把未解决项和需要补的材料继续交给相应负责人，不能因为每个输入框都有字就判定需求无歧义。 把明确答复、来源及未决边界整理进最终需求总结。遵循当前 DSH 工具 schema 与需求分析元技能完成记录和最终用户确认；HTML 的 `passed_by_card` 只表示页面填写完整，不能替代需求版本的正式确认。模板注释中的函数名不代表宿主实际存在该工具。