--- name: "ads-clarify" description: "通过最多 5 个高度针对性的澄清问题，识别当前功能 spec 中欠明确的区域，并将答案编码回 spec 文件。" agent_created: true argument-hint: "spec 中需要澄清的可选区域" compatibility: "需要 adspecs 项目结构及 docs/ 目录" metadata: author: "Qingwen Chen" user-invocable: true disable-model-invocation: false --- ## 用户输入 ```text $ARGUMENTS ``` **必须** 在继续之前考虑用户输入（如果非空）。 ## 执行前检查 **检查扩展钩子（澄清前）**: - 检查项目根目录是否存在 `.adspecs/extensions.yml`。 - 如果存在，读取它并查找 `hooks.before_clarify` 下的条目。 - 如果 YAML 无法解析或无效，静默跳过钩子检查并继续正常执行。 - 过滤掉 `enabled` 明确为 `false` 的钩子。没有 `enabled` 字段的钩子默认视为启用。 - 对于每个剩余的钩子，**不要** 尝试解释或评估钩子的 `condition` 表达式： - 如果钩子没有 `condition` 字段，或为空/null，视为可执行。 - 如果钩子定义了非空的 `condition`，跳过该钩子，将条件评估留给 HookExecutor 实现。 - 从钩子命令名构造斜杠命令时，将点号（`.`）替换为连字符（`-`）。例如：`adspecs.git.commit` → `/ads-git-commit`。 - 对于每个可执行钩子，根据其 `optional` 标志输出以下内容： - **可选钩子** (`optional: true`): ``` ## 扩展钩子 **可选前置钩子**: {extension} 命令: `/{command}` 描述: {description} 提示: {prompt} 执行: `/{command}` ``` - **必选钩子** (`optional: false`): ``` ## 扩展钩子 **自动前置钩子**: {extension} 执行: `/{command}` EXECUTE_COMMAND: {command} 等待钩子命令结果后再继续执行 Outline。 ``` - 如果没有注册钩子或 `.adspecs/extensions.yml` 不存在，静默跳过。 ## 概述 目标：检测并减少当前功能 spec 中的模糊性或缺失的决策点，并将澄清记录直接写入 spec 文件。 注意：此澄清工作流预期在调用 `/ads-plan` **之前** 运行（并完成）。如果用户明确表示跳过澄清（例如探索性 spike），可以继续，但必须警告下游返工风险增加。 执行步骤： 1. 根据当前操作系统选择对应脚本，从仓库根目录运行 **一次**，解析输出的 JSON： - **Windows (PowerShell)**: `.adspecs/scripts/powershell/check-prerequisites.ps1 -Json -PathsOnly` - **macOS/Linux (Bash)**: `.adspecs/scripts/bash/check-prerequisites.sh --json --paths-only` - 解析最小 JSON 负载字段： - `FEATURE_DIR` - `FEATURE_SPEC` - （可选捕获 `IMPL_PLAN`、`TASKS` 供未来的链式流程使用。） - 如果 JSON 解析失败，中止并指示用户重新运行 `/ads-prd` 或验证 feature branch 环境。 - 对于参数中的单引号如 "I'm Groot"，使用转义语法：例如 'I'\''m Groot'（或如果可能，使用双引号："I'm Groot"）。 2. 加载当前 spec 文件。使用以下分类法执行结构化模糊度和覆盖度扫描。为每个类别标记状态：Clear / Partial / Missing。生成用于优先排序的内部覆盖度映射（不要输出原始映射，除非没有问题可问）。 功能范围与行为： - 核心用户目标与成功标准 - 明确的范围外声明 - 用户角色/人物的区分 领域与数据模型： - 实体、属性、关系 - 标识与唯一性规则 - 生命周期/状态转换 - 数据量/规模假设 交互与 UX 流程： - 关键用户旅程/序列 - 错误/空/加载状态 - 无障碍或本地化说明 非功能质量属性： - 性能（延迟、吞吐量目标） - 可扩展性（水平/垂直，限制） - 可靠性与可用性（正常运行时间、恢复预期） - 可观测性（日志、指标、链路追踪信号） - 安全与隐私（认证/授权、数据保护、威胁假设） - 合规/监管约束（如有） 集成与外部依赖： - 外部服务/API 及其故障模式 - 数据导入/导出格式 - 协议/版本假设 边界情况与故障处理： - 反向场景 - 速率限制/节流 - 冲突解决（例如并发编辑） 约束与权衡： - 技术约束（语言、存储、托管） - 明确的权衡或已否决的替代方案 术语与一致性： - 规范术语表 - 避免的同义词 / 弃用术语 完成信号： - 验收标准的可测试性 - 可度量的 Definition of Done 风格指标 杂项 / 占位符： - TODO 标记 / 未解决的决策 - 缺乏量化的模糊形容词（"健壮"、"直观"等） 功能清单检查 - 一级模块/二级模块的名称和编号是否与 `docs/10-architecture/01-smom-wms_business_architecture.md` 中 §2.1 模块清单、§2.2 子模块清单对齐一致性检查 - 二级菜单/模块划分合理性检查 对于每个标记为 Partial 或 Missing 的类别，添加候选问题机会，除非： - 澄清不会实质性改变实现或验证策略。 - 信息更适合推迟到计划阶段（内部注明）。 3. 生成（内部）优先级排序的候选澄清问题队列（最多 5 个）。**不要** 一次性全部输出。应用以下约束： - 整个会话最多 5 个问题。 - 每个问题必须能够以以下任一方式回答： - 简短的多项选择（2-5 个互斥的选项），或 - 一个单词 / 简短短语的回答（明确约束："用 ≤5 个词回答"）。 - 仅包含答案会实质性影响架构、数据建模、任务分解、测试设计、UX 行为、运维就绪或合规验证的问题。 - 确保类别覆盖平衡：优先覆盖影响最大的未解决类别；避免在单个高影响领域（如安全姿态）未解决时，问两个低影响问题。 - 排除已回答的问题、琐碎的风格偏好或计划层面的执行细节（除非阻碍正确性）。 - 优先考虑能够降低下游返工风险或防止验收测试偏差的澄清。 - 如果超过 5 个类别仍未解决，按（影响 × 不确定性）启发性公式选择前 5 个。 4. 顺序提问循环（交互式）： - **每次仅呈现一个问题**。 - 对于多项选择问题： - **分析所有选项** 并根据以下因素确定 **最合适的选项**： - 项目类型的最佳实践 - 类似实现中的常见模式 - 风险降低（安全性、性能、可维护性） - 与 spec 中可见的任何明确项目目标或约束的一致性 - 在顶部醒目呈现你的 **推荐选项**，附上清晰的理由（1-2 句话解释为什么这是最佳选择）。 - 格式：`**推荐:** 选项 [X] - <理由>` - 然后将所有选项呈现为 Markdown 表格： | 选项 | 描述 | | ---- | ------------------------------------------------------------- | | A | <选项 A 描述> | | B | <选项 B 描述> | | C | <选项 C 描述>（根据需要添加 D/E，最多 5 个） | | 简短 | 提供一个不同的简短答案（≤5 词）（仅在自由形式替代合适时包含） | - 表格后添加：`你可以回复选项字母（如 "A"），回复 "yes" 或 "recommended" 接受推荐，或提供你自己的简短答案。` - 对于简短回答风格（没有有意义的分立选项）： - 根据最佳实践和上下文提供你的 **建议答案**。 - 格式：`**建议:** <你提出的答案> - <简要理由>` - 然后输出：`格式：简短答案（≤5 词）。你可以回复 "yes" 或 "suggested" 接受建议，或提供你自己的答案。` - 用户回答后： - 如果用户回复 "yes"、"recommended" 或 "suggested"，使用你先前陈述的推荐/建议作为答案。 - 否则，验证答案是否映射到某个选项或符合 ≤5 词约束。 - 如果模糊不清，要求快速消歧（计数仍属于同一问题；不推进）。 - 一旦满意，记录到工作内存中（暂不写入磁盘），并移至下一个排队问题。 - 在以下情况下停止提问： - 所有关键模糊点提前解决（剩余排队项变得不必要），或 - 用户发出完成信号（"done"、"good"、"no more"），或 - 达到 5 个已问问题。 - 永远不要提前透露未来排队的问题。 - 如果一开始就没有有效问题，立即报告没有关键模糊点。 5. 每次接受答案后的集成（增量更新方法）： - 维护 spec 的内存表示（启动时加载一次）以及原始文件内容。 - 对于本次会话中第一个集成的答案： - 确保存在 `## 澄清记录` 部分（如果缺失，在 spec 模板中最高层级上下文/概述部分之后创建）。 - 在其下创建（如果不存在）`### 会话 YYYY-MM-DD` 子标题（当天日期）。 - 在接受后立即追加一行项目符号：`- Q: <问题> → A: <最终答案>`。 - 然后立即将澄清应用到最合适的部分： - 功能模糊 → 更新或在功能需求中添加项目符号。 - 用户交互/角色区分 → 使用澄清的角色、约束或场景更新用户故事或角色子部分（如果存在）。 - 数据形状/实体 → 更新数据模型（添加字段、类型、关系）保持顺序；简洁记录新增约束。 - 非功能约束 → 在成功标准 > 可度量结果中添加/修改可度量标准（将模糊形容词转换为指标或明确目标）。 - 边界情况/负面流程 → 在边界情况/错误处理下添加新项目符号（或如果模板提供了占位符，则创建该子部分）。 - 术语冲突 → 在整个 spec 中规范化术语；仅在有需要时保留原始术语，添加 `（曾称为"X"）` 一次。 - 如果澄清使先前的模糊陈述无效，替换该陈述而非重复；不留下过时的矛盾文本。 - 在**每次**集成后保存 spec 文件，以最小化上下文丢失的风险（原子覆写）。 - 保留格式：不重新排序无关部分；保持标题层次结构完整。 - 保持每个插入的澄清最小且可测试（避免叙述漂移）。 6. 验证（每次写入后加最终一次执行）： - 澄清会话每个接受的答案恰好包含一个项目符号（无重复）。 - 总计已问（已接受）问题 ≤ 5。 - 更新后的部分没有本应由新答案解决的遗留模糊占位符。 - 没有保留矛盾的前一陈述（扫描已删除的现已无效的替代选项）。 - Markdown 结构有效；仅允许的新标题：`## 澄清记录`、`### 会话 YYYY-MM-DD`。 - 术语一致性：所有更新部分使用相同的规范术语。 7. 将更新后的 spec 写回 `FEATURE_SPEC`。 8. **重新验证 Spec 质量检查清单**（如果存在）： - 检查 `FEATURE_DIR/checklists/requirements.md` 是否存在。 - 如果 **不** 存在，静默跳过此步骤。 - 如果存在： 1. 读取检查清单文件。 2. 识别所有 GitHub 任务列表复选框行 — 匹配 `- [ ]`、`- [x]` 或 `- [X]`（不区分大小写，容忍前导空白用于嵌套项）且不在代码块内的行。忽略所有其他内容（标题、注释、非复选框项目符号、元数据）。 3. 对于每个复选框行，记录其当前标记状态（已勾选或未勾选）和项文本到之前快照列表中。 4. 根据 **更新后** 的 spec（步骤 7 刚保存的版本）重新评估每个复选框项。 5. 对于每个复选框项，仅在勾选/未勾选状态实际发生变化时更新： - 如果该项现在通过且之前未勾选：将 `[ ]` 改为 `[x]`。 - 如果该项现在失败且之前已勾选：将 `[x]`/`[X]` 改为 `[ ]`。 - 如果状态未改变：保持标记原样（保留现有大小写以避免外观差异）。 6. 保存更新后的检查清单文件。**仅切换状态发生变化的复选框行的 `[ ]`/`[x]` 标记部分。** 所有其他文件内容 — 标题、元数据、注释、行顺序、空白 — 必须保持不变以避免杂讯差异。 7. 比较之前快照与当前状态，计算完成报告的三个列表： - **新通过**: 从未勾选变为已勾选的项。 - **退回**: 从已勾选变为未勾选的项。 - **仍不通过**: 保持未勾选的项。 8. 记录之前/之后通过数为已勾选/总复选框项数（例如 "12/16 → 15/16 items passing"）。 行为规则： - 如果没有发现有意义模糊点（或所有潜在问题都是低影响的），回复："未检测到值得正式澄清的关键模糊点。" 并建议继续。 - 如果 spec 文件缺失，指示用户先运行 `/ads-prd`（不要在此创建新 spec）。 - 永远不要超过 5 个已问问题（对单个问题的澄清重试不计为新问题）。 - 避免推测性技术栈问题，除非其缺失阻碍功能清晰性。 - 尊重用户提前终止信号（"stop"、"done"、"proceed"）。 - 如果因覆盖完全而没有问问题，输出紧凑的覆盖度摘要（所有类别 Clear），然后建议推进。 - 如果配额用完但仍有高影响未解决类别，在"推迟"下明确标记它们并附上理由。 优先级排序上下文：$ARGUMENTS ## 必选执行后钩子 **必须在向用户报告完成之前完成本节。** 检查项目根目录是否存在 `.adspecs/extensions.yml`。 - 如果不存在，或 `hooks.after_clarify` 下没有注册钩子，跳到完成报告。 - 如果存在，读取它并查找 `hooks.after_clarify` 下的条目。 - 如果 YAML 无法解析或无效，静默跳过钩子检查并继续完成报告。 - 过滤掉 `enabled` 明确为 `false` 的钩子。没有 `enabled` 字段的钩子默认视为启用。 - 对于每个剩余的钩子，**不要** 尝试解释或评估钩子的 `condition` 表达式： - 如果钩子没有 `condition` 字段，或为空/null，视为可执行。 - 如果钩子定义了非空的 `condition`，跳过该钩子，将条件评估留给 HookExecutor 实现。 - 从钩子命令名构造斜杠命令时，将点号（`.`）替换为连字符（`-`）。例如：`adspecs.git.commit` → `/ads-git-commit`。 - 对于每个可执行钩子，根据其 `optional` 标志输出以下内容： - **必选钩子** (`optional: false`) — **必须为每个必选钩子发出 `EXECUTE_COMMAND:`**： ``` ## 扩展钩子 **自动钩子**: {extension} 执行: `/{command}` EXECUTE_COMMAND: {command} ``` - **可选钩子** (`optional: true`): ``` ## 扩展钩子 **可选钩子**: {extension} 命令: `/{command}` 描述: {description} 提示: {prompt} 执行: `/{command}` ``` ## 完成报告 报告完成（提问循环结束或提前终止后）： - 已问和已回答的问题数量。 - 更新后的 spec 路径。 - 涉及的章节（列出名称）。 - Spec 质量检查清单状态（如果 `FEATURE_DIR/checklists/requirements.md` 被重新验证）：显示之前/之后通过数（例如 "Spec Quality Checklist: 12/16 → 15/16 items passing"）并列出任何状态发生变化的项 — 包括新增已勾选（未勾选 → 已勾选）和任何退回（已勾选 → 未勾选）。如果有任何项仍未勾选，将它们列为需要关注的领域。 - 覆盖度摘要表，列出每个分类法类别的状态：Resolved（之前 Partial/Missing 且已处理）、Deferred（超过问题配额或更适合计划阶段处理）、Clear（已足够）、Outstanding（仍 Partial/Missing 但低影响）。 - 如果存在任何 Outstanding 或 Deferred，建议是继续 `/ads-plan` 还是在计划后再次运行 `/ads-clarify`。 - 建议的下一步命令。 ## 完成标志 - [ ] Spec 模糊点已识别，澄清已集成到 spec 文件 - [ ] Spec 质量检查清单已根据更新后的 spec 重新验证（如果 `FEATURE_DIR/checklists/requirements.md` 存在） - [ ] 扩展钩子已根据上述必选执行后钩子规则分发或跳过 - [ ] 完成报告已呈现给用户，包含已问问题数、涉及章节、检查清单状态和覆盖度摘要