checklist

检查清单生成技能

清单核心概念

清单是需求编写的单元测试 — 验证特定领域中需求的质量、清晰度和完整性.

不用于验证/测试:

• 不是"验证按钮点击正确"
• 不是"测试错误处理有效"
• 不是检查代码/实现是否符合规范

用于需求质量验证:

• "是否为所有卡片类型定义了视觉层次需求？"(完整性)
• "'突出显示'是否通过具体尺寸/位置进行了量化？"(清晰度)
• "所有交互元素的悬停状态需求是否一致？"(一致性)

用户输入

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

执行步骤

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 linux: scripts/bash/check-prerequisites.sh --json
• 解析 JSON 以获取 FEATURE_DIR 和 AVAILABLE_DOCS 列表
• 所有文件路径必须是绝对路径
• 对于参数中的单引号如 "I'm Groot", 使用转义语法: 例如 'I'''m Groot'(或优先使用双引号)

2. 澄清意图(动态)

推导最多三个初始上下文澄清问题(无预编目录). 它们必须:

• 从用户的表述 + 从规范/计划/任务中提取的信号生成
• 只询问实质上改变清单内容的信息
• 如果在用户输入中已经明确, 则跳过
• 优先考虑精确性而非广度

生成算法:

1. 提取信号: 功能领域关键词、风险指标、利益相关者提示、显式交付物
2. 将信号聚类为候选焦点区域(最多 4 个), 按相关性排序
3. 识别可能的受众和时间(作者、审查者、QA、发布)
4. 检测缺失维度: 范围广度、深度/严格性、风险重点、排除边界、可测量验收标准
5. 从以下原型中选择问题:
   • 范围细化、风险优先级、深度校准、受众框架、边界排除、场景类别缺口

问题格式规则:

• 如果提供选项, 生成紧凑表格(Option | Candidate | Why It Matters)
• 最多 A-E 选项; 自由形式更清晰时省略表格
• 不要让用户重述已说内容

交互不可能时的默认值:

• 深度: Standard
• 受众: Reviewer(PR, 代码相关); Author(其他)
• 焦点: 前 2 个相关性聚类

输出问题(标记 Q1/Q2/Q3). 回答后若 >=2 个场景类别仍不清楚, 可追问最多 2 个(Q4/Q5), 总计不超过 5 个问题.

3. 理解用户请求

结合用户输入 + 澄清答案:

• 推导清单主题(例如: security, review, deploy, ux)
• 整合用户明确提到的必需项目
• 将焦点选择映射到类别框架
• 从规范/计划/任务中推断缺失上下文(不要虚构)

4. 加载功能上下文

从 FEATURE_DIR 读取:

• spec.md: 功能需求和范围
• design.md(如果存在): 技术细节、依赖关系
• tasks.md(如果存在): 实施任务

上下文加载策略:

• 仅加载与活动焦点区域相关的必要部分
• 优先将长部分总结为简洁的场景/需求要点
• 使用渐进式披露: 仅在检测到差距时添加后续检索

5. 生成清单

创建 FEATURE_DIR/checklists/ 目录(如果不存在). 生成唯一清单文件名:

• 使用短描述性名称(例如 ux.md, api.md, security.md)
• 如果文件已存在, 追加到现有文件
• 每次运行创建新文件(不覆盖现有清单)
• 项目从 CHK001 开始顺序编号

核心原则 — 测试需求, 而非实现:

每个清单项目必须评估需求本身, 检查:

• 完整性: 所有必要的需求是否存在？
• 清晰度: 需求是否明确无歧义且具体？
• 一致性: 需求之间是否相互一致？
• 可测量性: 需求是否可以客观验证？
• 覆盖度: 是否涵盖了所有场景/边缘情况？

类别结构 — 按需求质量维度分组:

• 需求完整性、需求清晰度、需求一致性
• 验收标准质量、场景覆盖度、边缘情况覆盖度
• 非功能性需求、依赖关系和假设、歧义和冲突

项目结构:

• 问题格式, 询问需求质量
• 聚焦于规范中写了什么(或没写什么)
• 括号标注质量维度 [Completeness/Clarity/Consistency/etc.]
• 引用规范章节 [Spec §X.Y]
• 缺失需求使用 [Gap] 标记

场景分类与覆盖度:

• 检查需求是否存在: Primary, Alternate, Exception/Error, Recovery, Non-Functional 场景
• 缺失的场景类别标记为 [Gap]
• 涉及状态变更时包含回滚需求检查

可追溯性要求:

• 最低 >=80% 的项目必须包含至少一个可追溯性引用
• 引用格式: [Spec §X.Y] 或标记 [Gap], [Ambiguity], [Conflict], [Assumption]

内容整合:

• 软上限: 原始候选项 > 40 时按风险/影响优先级排序
• 合并检查相同需求方面的近重复项
• 低影响边缘情况 > 5 个时合并为一个项目

禁止模式(这些会使其成为实现测试):

• 以 "Verify"、"Test"、"Confirm"、"Check" + 实现行为开头的项目
• 引用代码执行、用户操作、系统行为
• "Displays correctly"、"works properly"、"Click"、"navigate"、"render"

必需模式(测试需求质量):

• "Are [requirement type] defined/specified/documented for [scenario]?"
• "Is [vague term] quantified/clarified with specific criteria?"
• "Are requirements consistent between [section A] and [section B]?"
• "Can [requirement] be objectively measured/verified?"

6. 结构参考

按照 .infra/templates/checklist-template.md 中的规范模板生成清单. 如果模板不可用, 使用: H1 标题、purpose/created 元行、包含 - [ ] CHK### <requirement item> 行的 ## 类别部分, ID 从 CHK001 开始全局递增.

7. 报告

输出创建清单的完整路径、项目数量, 并提醒用户每次运行都会创建新文件. 总结:

• 选择的焦点区域
• 深度级别
• 执行者/时间
• 任何整合的用户明确指定的必需项目

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

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

示例清单类型和示例项目

详见 examples.md 了解各类型清单(UX、API、性能、安全)的示例项目和正确/错误对比.