adspecs 0.1.12

package/skills/adspecs-clarify/SKILL.md

@@ -0,0 +1,299 @@
+---
+name: "adspecs-clarify"
+description: "通过最多 5 个高度针对性的澄清问题，识别当前功能 spec 中欠明确的区域，并将答案编码回 spec 文件。"
+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` → `/adspecs-git-commit`。
+- 对于每个可执行钩子，根据其 `optional` 标志输出以下内容：
+  - **可选钩子** (`optional: true`):
+
+    ```
+    ## 扩展钩子
+
+    **可选前置钩子**: {extension}
+    命令: `/{command}`
+    描述: {description}
+
+    提示: {prompt}
+    执行: `/{command}`
+    ```
+
+  - **必选钩子** (`optional: false`):
+
+    ```
+    ## 扩展钩子
+
+    **自动前置钩子**: {extension}
+    执行: `/{command}`
+    EXECUTE_COMMAND: {command}
+
+    等待钩子命令结果后再继续执行 Outline。
+    ```
+
+- 如果没有注册钩子或 `.adspecs/extensions.yml` 不存在，静默跳过。
+
+## 概述
+
+目标：检测并减少当前功能 spec 中的模糊性或缺失的决策点，并将澄清记录直接写入 spec 文件。
+
+注意：此澄清工作流预期在调用 `/adspecs-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 解析失败，中止并指示用户重新运行 `/adspecs-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 文件缺失，指示用户先运行 `/adspecs-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` → `/adspecs-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，建议是继续 `/adspecs-plan` 还是在计划后再次运行 `/adspecs-clarify`。
+- 建议的下一步命令。
+
+## 完成标志
+
+- [ ] Spec 模糊点已识别，澄清已集成到 spec 文件
+- [ ] Spec 质量检查清单已根据更新后的 spec 重新验证（如果 `FEATURE_DIR/checklists/requirements.md` 存在）
+- [ ] 扩展钩子已根据上述必选执行后钩子规则分发或跳过
+- [ ] 完成报告已呈现给用户，包含已问问题数、涉及章节、检查清单状态和覆盖度摘要