| 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_DIRFEATURE_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")
- 如果由于完全覆盖而没有提问, 输出紧凑的覆盖范围摘要然后建议前进
- 如果达到配额但仍有未解决的高影响类别, 在已推迟下明确标记并附上理由
