clarify

name	clarify
description	规范澄清技能. 通过提出最多 5 个高度针对性的澄清问题, 识别当前功能规范中未充分说明的领域, 并将答案编码回规范中. 当用户提到澄清规范、消除模糊性、补充规范细节、或在 specify 完成后需要进一步细化时使用.

规范澄清

目标

检测并减少活跃功能规范中的模糊性或缺失的决策点, 并将澄清内容直接记录在规范文件中.

注意: 此澄清工作流应在 /design 之前运行(并完成). 如果用户明确表示跳过澄清(例如, 探索性原型), 可以继续, 但必须警告下游返工风险增加.

用户输入

在继续之前, 你必须考虑用户的消息内容(如果不为空).

执行步骤

0. skill执行开始时间打点记录

开始执行步骤之前，需要进行一些打点记录工作，记录本skill的执行时间到 start_time字段：

• 判断当前操作系统，windows还是linux系统;
• 针对不同操作系统运行脚本获取配置 windows: Get-Date -Format "yyyy-MM-dd HH:mm:ss" linux: date +"%Y-%m-%d %H:%M:%S"
• 将获取的时间记录到 start_time

1. 设置

• 判断当前操作系统, windows 还是 linux 系统;
• 针对不同操作系统从仓库根目录运行脚本一次 windows: scripts/powershell/check-prerequisites.ps1 --json --paths-only linux: scripts/bash/check-prerequisites.sh --json --paths-only
• 解析最小 JSON 负载字段:
  • FEATURE_DIR
  • FEATURE_SPEC
  • (可选捕获 IMPL_DESIGN、TASKS 用于未来的链式流程.)
• 如果 JSON 解析失败, 中止并指示用户重新运行 /specify 或验证功能分支环境.
• 对于参数中包含单引号的情况(如 "I'm Groot"), 使用转义语法: 例如 'I'''m Groot'(或优先使用双引号: "I'm Groot").

2. 结构化模糊性扫描

加载当前规范文件. 使用以下分类法执行扫描, 对每个类别标记状态: 清晰 / 部分 / 缺失. 生成内部覆盖范围图(除非不会提问, 否则不输出原始图).

功能范围与行为:

• 核心用户目标和成功标准
• 明确的超出范围声明
• 用户角色 / 角色区分

领域与数据模型:

• 实体、属性、关系
• 身份和唯一性规则
• 生命周期 / 状态转换
• 数据量 / 规模假设

交互与 UX 流程:

• 关键用户旅程 / 序列
• 错误 / 空白 / 加载状态
• 可访问性或本地化说明

非功能性质量属性:

• 性能(延迟、吞吐量目标)
• 可扩展性(水平 / 垂直、限制)
• 可靠性和可用性(正常运行时间、恢复期望)
• 可观察性(日志、指标、追踪信号)
• 安全性和隐私(身份验证 / 授权、数据保护、威胁假设)
• 合规性 / 监管约束(如有)

集成与外部依赖:

• 外部服务 / API 和故障模式
• 数据导入 / 导出格式
• 协议 / 版本控制假设

边缘情况与故障处理:

• 负面场景
• 速率限制 / 节流
• 冲突解决(例如, 并发编辑)

约束与权衡:

• 技术约束(语言、存储、托管)
• 明确的权衡或被拒绝的替代方案

术语与一致性:

• 规范术语表术语
• 避免的同义词 / 已弃用术语

完成信号:

• 验收标准可测试性
• 可衡量的完成定义风格指标

其他 / 占位符:

• TODO 标记 / 未解决的决策
• 缺少量化的模糊形容词("robust"、"intuitive")

对于每个处于部分或缺失状态的类别, 添加候选问题机会, 除非:

• 澄清不会实质性地改变实施或验证策略
• 信息更适合推迟到规划阶段(内部记录)

3. 生成候选问题队列

(内部)生成候选澄清问题的优先级队列(最多 5 个). 不要一次性输出所有问题. 应用以下约束:

• 整个会话最多 10 个问题
• 每个问题必须可以用以下任一方式回答:
  • 简短的多项选择(2-5 个不同的、互斥的选项)
  • 单词 / 短语答案(明确约束: "Answer in <=5 words")
• 仅包含答案实质上影响架构、数据建模、任务分解、测试设计、UX 行为、运营准备或合规性验证的问题
• 确保类别覆盖平衡: 首先覆盖最高影响的未解决类别; 避免在单个高影响领域未解决时询问两个低影响问题
• 排除已回答的问题、琐碎的风格偏好或规划级别的执行细节(除非阻碍正确性)
• 偏好减少下游返工风险或防止不一致验收测试的澄清
• 如果超过 5 个类别仍未解决, 通过(影响 * 不确定性)启发式选择前 5 个

4. 顺序提问流程(交互式)

• 一次只提出确切一个问题

• 对于多项选择题:

  • 分析所有选项并基于以下确定最合适的选项:

    • 项目类型的最佳实践
    • 类似实现中的常见模式
    • 风险降低(安全性、性能、可维护性)
    • 与规范中可见的任何明确项目目标或约束的一致性

  • 在顶部突出显示推荐选项并附上清晰推理(1-2 句话)

  • 格式为: **Recommended:** Option [X] - <reasoning>

  • 然后将所有选项渲染为 Markdown 表格:

    Option	Description
    A	Option A description
    B	Option B description
    Short	Provide a different short answer (<=5 words)

  • 表格后添加: You can reply with the option letter (e.g., "A"), accept the recommendation by saying "yes" or "recommended", or provide your own short answer.

• 对于简答题风格(没有有意义的不同选项):

  • 基于最佳实践和上下文提供建议答案
  • 格式为: **Suggested:** <your proposed answer> - <brief reasoning>
  • 然后输出: Format: Short answer (<=5 words). You can accept the suggestion by saying "yes" or "suggested", or provide your own answer.

• 用户回答后:

  • 如果用户回复 "yes"、"recommended" 或 "suggested", 使用之前陈述的推荐 / 建议作为答案
  • 否则, 验证答案映射到一个选项或符合 <=5 个词的约束
  • 如果模糊, 要求快速消除歧义(计数仍属于同一问题; 不前进)
  • 一旦满意, 将其记录在工作内存中(尚未写入磁盘)并移动到下一个排队的问题

• 在以下情况时停止进一步提问:

  • 所有关键模糊性早期解决(剩余排队项目变得不必要)
  • 用户发出完成信号("done"、"good"、"no more")
  • 达到 5 个已问问题

• 永远不要提前揭示未来的排队问题

• 如果开始时没有有效问题, 立即报告没有关键模糊性

5. 增量集成答案

每次接受答案后:

• 维护规范的内存表示(开始时加载一次)加上原始文件内容
• 对于此会话中第一个集成的答案:
  • 确保 ## Clarifications 部分存在(如果缺失, 根据规范模板在最高级别的上下文 / 概述部分之后创建)
  • 在其下创建(如果不存在)今天的 ### Session YYYY-MM-DD 子标题
• 接受后立即追加项目符号行: - Q: <question> -> A: <final answer>
• 然后立即将澄清应用到最合适的部分:
  • 功能模糊性 -> 更新或在功能需求中添加项目符号
  • 用户交互 / 角色区分 -> 更新用户故事或角色子部分
  • 数据形状 / 实体 -> 更新数据模型(添加字段、类型、关系)
  • 非功能性约束 -> 在非功能性 / 质量属性部分添加 / 修改可衡量标准
  • 边缘情况 / 负面流程 -> 在边缘情况 / 错误处理下添加新项目符号
  • 术语冲突 -> 在整个规范中规范化术语
• 如果澄清使早期模糊声明无效, 替换该声明而不是重复
• 每次集成后保存规范文件以最小化上下文丢失风险(原子覆盖)
• 保持格式: 不重新排序不相关的部分; 保持标题层次结构完整
• 保持每个插入的澄清最小化和可测试

6. 验证

每次写入后执行, 最终再进行一次完整检查:

• 澄清会话每个接受的答案只包含一个项目符号(无重复)
• 总共询问(接受)的问题 <= 5
• 更新的部分不包含新答案旨在解决的持续模糊占位符
• 没有矛盾的早期声明保留
• Markdown 结构有效; 仅允许新标题: ## Clarifications、### Session YYYY-MM-DD
• 术语一致性: 所有更新部分使用相同的规范术语

7. 写回规范

将更新的规范写回 FEATURE_SPEC.

8. 规范质量评测

加载 evaluation-rubric skill 的四维量规，对更新后的 FEATURE_SPEC 执行评测：

• Business Value / Technical Completeness / Clarity & Testability / Traceability（各 25 分）
• 输出: 追加到 FEATURE_DIR/.runs/evaluations/evaluation-report.yaml（stage: clarify）
• 通过标准: overall_score >= 95

若不通过: 修复规范中对应维度的问题，重新评测（最多 2 轮），结果记入步骤 9 完成报告。

9. 完成报告

提问循环结束或提前终止后输出:

• 询问和回答的问题数量
• 更新规范的路径
• 涉及的部分(列出名称)
• 覆盖范围摘要表, 列出每个分类类别及状态: 已解决 / 已推迟 / 清晰 / 未完成
• 如果有未完成或已推迟的剩余, 建议是继续到 /design 还是再次运行澄清
• 建议的下一个命令

10. 记录本skill的运行日志信息

执行runlog-record skill，请将前面获取到的start_time的值作为参数传入runlog-record skill

行为规则

• 如果没有发现有意义的模糊性, 回应: "No critical ambiguities detected worth formal clarification." 并建议继续
• 如果规范文件缺失, 指示用户首先运行 /specify(不要在此创建新规范)
• 永远不要超过总共 5 个询问的问题(单个问题的澄清重试不计为新问题)
• 避免推测性技术堆栈问题, 除非缺失阻碍功能清晰性
• 尊重用户提前终止信号("stop"、"done"、"proceed")
• 如果由于完全覆盖而没有提问, 输出紧凑的覆盖范围摘要然后建议前进
• 如果达到配额但仍有未解决的高影响类别, 在已推迟下明确标记并附上理由