| name | checklist |
| description | 根据用户需求为当前功能生成自定义检查清单。 |
| disable-model-invocation | true |
| allowed-tools | ["Bash(node */check-prerequisites.mjs*)"] |
检查清单目的："英文的单元测试"
关键概念：检查清单是需求编写的单元测试——它们验证给定领域中需求的质量、清晰度和完整性。
不是用于验证/测试：
- ❌ 不是 "验证按钮点击正确"
- ❌ 不是 "测试错误处理是否工作"
- ❌ 不是 "确认 API 返回 200"
- ❌ 不是检查代码/实现是否匹配规格
用于需求质量验证：
- ✅ "是否为所有卡片类型定义了视觉层次需求？"（完整性）
- ✅ "'突出显示'是否用具体的尺寸/位置量化？"（清晰度）
- ✅ "所有交互元素的悬停状态需求是否一致？"（一致性）
- ✅ "是否定义了键盘导航的无障碍需求？"（覆盖度）
- ✅ "规格是否定义了 logo 图片加载失败时会发生什么？"（边界情况）
隐喻：如果你的规格是用英文编写的代码，检查清单就是它的单元测试套件。你在测试需求是否编写良好、完整、无歧义且准备好实现——不是测试实现是否工作。
用户输入
$ARGUMENTS
你必须在继续之前考虑用户输入（如果不为空）。
执行步骤
-
设置：从仓库根目录运行 node ${WAVE_PLUGIN_ROOT}/scripts/check-prerequisites.mjs --json 并解析 JSON 获取 FEATURE_DIR 和 AVAILABLE_DOCS 列表。
- 所有文件路径必须是绝对路径。
- 对于参数中的单引号如 "I'm Groot"，使用转义语法：例如 'I'''m Groot'（或尽可能使用双引号："I'm Groot"）。
-
明确意图（动态）：派生最多三个初始上下文澄清问题（无预制目录）。它们必须：
- 从用户的措辞 + 规格/计划/任务中提取的信号生成
- 仅询问实质性改变检查清单内容的信息
- 如果
$ARGUMENTS 中已经明确则单独跳过
- 优先精度而非广度
生成算法：
- 提取信号：功能领域关键词（例如 auth、延迟、UX、API）、风险指标（"关键"、"必须"、"合规"）、利益相关者提示（"QA"、"审查"、"安全团队"）和明确交付物（"a11y"、"回滚"、"契约"）。
- 将信号聚类为候选焦点区域（最多 4 个）按相关性排名。
- 识别可能的受众和时机（作者、审查者、QA、发布）如果不明确。
- 检测缺失维度：范围广度、深度/严谨性、风险强调、排除边界、可衡量的验收标准。
- 从这些原型中选择制定问题：
- 范围细化（例如，"这应该包括与 X 和 Y 的集成触点还是仅限于本地模块正确性？"）
- 风险优先级（例如，"这些潜在风险区域中哪些应该接受强制性门禁检查？"）
- 深度校准（例如，"这是轻量级的提交前健全性列表还是正式的发布门禁？"）
- 受众框架（例如，"这将仅由作者使用还是在 PR 审查期间由同行使用？"）
- 边界排除（例如，"我们应该在这一轮明确排除性能调优项目吗？"）
- 场景类缺口（例如，"未检测到恢复流程——回滚/部分失败路径在范围内吗？"）
问题格式规则：
- 如果提供选项，生成带有列的紧凑表格：选项 | 候选 | 为何重要
- 限制最多 A-E 选项；如果自由格式答案更清晰则省略表格
- 永远不要要求用户重述他们已经说过的内容
- 避免推测性类别（不臆造）。如不确定，明确询问："确认 X 是否属于范围内。"
无法交互时的默认值：
- 深度：标准
- 受众：审查者（PR）如果与代码相关；否则为作者
- 焦点：前 2 个相关性聚类
输出问题（标记 Q1/Q2/Q3）。回答后：如果 >=2 个场景类（替代/异常/恢复/非功能领域）仍不清楚，你可以再问最多两个有针对性的后续问题（Q4/Q5），每个有一行理由（例如，"未解决的恢复路径风险"）。不超过总共五个问题。如果用户明确拒绝更多则跳过升级。
-
理解用户请求：结合 $ARGUMENTS + 澄清答案：
- 派生检查清单主题（例如安全、审查、部署、ux）
- 合并用户提到的明确必需项目
- 将焦点选择映射到类别脚手架
- 从规格/计划/任务推断任何缺失上下文（不要臆造）
-
加载功能上下文：从 FEATURE_DIR 读取：
- spec.md：功能需求和范围
- plan.md（如存在）：技术细节、依赖
- tasks.md（如存在）：实现任务
上下文加载策略：
- 仅加载与活动焦点区域相关的必要部分（避免全文件转储）
- 优先将长章节总结为简洁的场景/需求要点
- 使用渐进式披露：仅在检测到缺口时添加后续检索
- 如果源文档很大，生成临时摘要项目而非嵌入原始文本
-
生成检查清单 - 创建"需求的单元测试"：
- 如果不存在则创建
FEATURE_DIR/checklists/ 目录
- 生成唯一的检查清单文件名：
- 使用基于领域的简短描述性名称（例如
ux.md、api.md、security.md）
- 格式：
[domain].md
- 如果文件存在，追加到现有文件
- 从 CHK001 开始顺序编号项目
- 每次
/checklist 运行创建一个新文件（从不覆盖现有检查清单）
核心原则 - 测试需求，而非实现：
每个检查清单项目必须评估需求本身的：
- 完整性：所有必要需求是否存在？
- 清晰度：需求是否无歧义且具体？
- 一致性：需求是否相互一致？
- 可衡量性：需求是否可以客观验证？
- 覆盖度：所有场景/边界情况是否已处理？
类别结构 - 按需求质量维度分组项目：
- 需求完整性（所有必要需求是否已文档化？）
- 需求清晰度（需求是否具体且无歧义？）
- 需求一致性（需求是否一致无冲突？）
- 验收标准质量（成功标准是否可衡量？）
- 场景覆盖度（所有流程/情况是否已处理？）
- 边界情况覆盖（边界条件是否已定义？）
- 非功能需求（性能、安全、无障碍等——是否已指定？）
- 依赖与假设（是否已文档化并验证？）
- 歧义与冲突（什么需要澄清？）
如何编写检查清单项目 - "英文的单元测试"：
❌ 错误（测试实现）：
- "验证登录页显示 3 个剧集卡片"
- "测试桌面端悬停状态是否工作"
- "确认 logo 点击导航到首页"
✅ 正确（测试需求质量）：
- "是否明确指定了精选剧集的确切数量和布局？" [完整性]
- "'突出显示'是否用具体的尺寸/位置量化？" [清晰度]
- "所有交互元素的悬停状态需求是否一致？" [一致性]
- "是否为所有交互 UI 定义了键盘导航需求？" [覆盖度]
- "是否指定了 logo 图片加载失败时的回退行为？" [边界情况]
- "是否为异步剧集数据定义了加载状态？" [完整性]
- "规格是否定义了竞争 UI 元素的视觉层次？" [清晰度]
项目结构：
每个项目应遵循此模式：
- 询问需求质量的问题格式
- 聚焦于已写的（或未写的）规格/计划内容
- 在括号中包含质量维度 [完整性/清晰度/一致性/等]
- 检查现有需求时引用规格章节
[规格 §X.Y]
- 检查缺失需求时使用
[缺口] 标记
按质量维度的示例：
完整性：
- "是否为所有 API 失败模式定义了错误处理需求？ [缺口]"
- "是否为所有交互元素指定了无障碍需求？ [完整性]"
- "是否为响应式布局定义了移动端断点需求？ [缺口]"
清晰度：
- "'快速加载'是否用具体的时机阈值量化？ [清晰度, 规格 §NFR-2]"
- "'相关剧集'的选择标准是否明确定义？ [清晰度, 规格 §FR-5]"
- "'突出'是否用可衡量的视觉属性定义？ [歧义, 规格 §FR-4]"
一致性：
- "导航需求是否在所有页面间一致？ [一致性, 规格 §FR-10]"
- "卡片组件需求在登录页和详情页之间是否一致？ [一致性]"
覆盖度：
- "是否为零状态场景（无剧集）定义了需求？ [覆盖度, 边界情况]"
- "是否处理了并发用户交互场景？ [覆盖度, 缺口]"
- "是否指定了部分数据加载失败的需求？ [覆盖度, 异常流程]"
可衡量性：
- "视觉层次需求是否可衡量/可测试？ [验收标准, 规格 §FR-1]"
- "'平衡的视觉权重'是否可以客观验证？ [可衡量性, 规格 §FR-2]"
场景分类与覆盖（需求质量焦点）：
- 检查是否存在以下场景的需求：主要、替代、异常/错误、恢复、非功能场景
- 对于每个场景类，问："[场景类型]需求是否完整、清晰且一致？"
- 如果场景类缺失："[场景类型]需求是有意排除还是缺失？ [缺口]"
- 发生状态变更时包括韧性/回滚："是否为迁移失败定义了回滚需求？ [缺口]"
可追溯性要求：
- 最低：>=80% 的项目必须包含至少一个可追溯性引用
- 每个项目应引用：规格章节
[规格 §X.Y]，或使用标记：[缺口]、[歧义]、[冲突]、[假设]
- 如无 ID 系统："是否建立了需求和验收标准 ID 方案？ [可追溯性]"
发现并解决问题（需求质量问题）：
询问关于需求本身的问题：
- 歧义："术语'快速'是否用具体指标量化？ [歧义, 规格 §NFR-1]"
- 冲突："§FR-10 和 §FR-10a 之间的导航需求是否冲突？ [冲突]"
- 假设"'播客 API 始终可用'的假设是否已验证？ [假设]"
- 依赖："外部播客 API 需求是否已文档化？ [依赖, 缺口]"
- 缺失定义："'视觉层次'是否用可衡量标准定义？ [缺口]"
内容整合：
- 软上限：如果原始候选项目 > 40，按风险/影响优先级排序
- 合并检查同一需求方面的近似重复项
- 如果 >5 个低影响边界情况，创建一个项目："边界情况 X、Y、Z 是否在需求中已处理？ [覆盖度]"
🚫 绝对禁止 - 这些使其成为实现测试而非需求测试：
- ❌ 任何以"验证"、"测试"、"确认"、"检查" + 实现行为开头项目
- ❌ 引用代码执行、用户操作、系统行为
- ❌ "显示正确"、"工作正常"、"按预期运行"
- ❌ "点击"、"导航"、"渲染"、"加载"、"执行"
- ❌ 测试用例、测试计划、QA 程序
- ❌ 实现细节（框架、API、算法）
✅ 必需模式 - 这些测试需求质量：
- ✅ "是否为 [场景] 定义/指定/文档化了 [需求类型]？"
- ✅ "[模糊术语] 是否用具体标准量化/澄清？"
- ✅ "[章节 A] 和 [章节 B] 之间的需求是否一致？"
- ✅ "[需求] 是否可以客观衡量/验证？"
- ✅ "需求中是否已处理 [边界情况/场景]？"
- ✅ "规格是否定义了 [缺失方面]？"
-
结构参考：按照 ${WAVE_PLUGIN_ROOT}/templates/checklist-template.md 中的规范模板生成检查清单，用于标题、元信息章节、类别标题和 ID 格式。如果模板不可用，使用：H1 标题、目的/创建元信息行、包含 - [ ] CHK### <需求项目> 行的 ## 类别章节，ID 从 CHK001 开始全局递增。
-
报告：输出创建的检查清单完整路径、项目计数，并提醒用户每次运行创建一个新文件。总结：
- 选择的焦点区域
- 深度级别
- 参与者/时机
- 合并的任何用户指定必需项目
重要：每次 /checklist 命令调用使用简短描述性名称创建检查清单文件，除非文件已存在。这允许：
- 不同类型的多个检查清单（例如
ux.md、test.md、security.md）
- 指示检查清单目的的简单易记文件名
- 在
checklists/ 文件夹中易于识别和导航
为避免混乱，使用描述性类型并在完成后清理过时的检查清单。
检查清单类型示例与示例项目
用户体验需求质量： ux.md
示例项目（测试需求，非实现）：
- "视觉层次需求是否用可衡量标准定义？ [清晰度, 规格 §FR-1]"
- "UI 元素的数量和定位是否明确指定？ [完整性, 规格 §FR-1]"
- "交互状态需求（悬停、焦点、激活）是否一致定义？ [一致性]"
- "是否为所有交互元素指定了无障碍需求？ [覆盖度, 缺口]"
- "图片加载失败时是否定义了回退行为？ [边界情况, 缺口]"
- "'突出显示'是否可以客观衡量？ [可衡量性, 规格 §FR-4]"
API 需求质量： api.md
示例项目：
- "是否为所有失败场景指定了错误响应格式？ [完整性]"
- "速率限制需求是否用具体阈值量化？ [清晰度]"
- "所有端点的认证需求是否一致？ [一致性]"
- "外部依赖的重试/超时需求是否已定义？ [覆盖度, 缺口]"
- "版本控制策略是否在需求中文档化？ [缺口]"
性能需求质量： performance.md
示例项目：
- "性能需求是否用具体指标量化？ [清晰度]"
- "是否为所有关键用户旅程定义了性能目标？ [覆盖度]"
- "不同负载条件下的性能需求是否已指定？ [完整性]"
- "性能需求是否可以客观衡量？ [可衡量性]"
- "高负载场景下的降级需求是否已定义？ [边界情况, 缺口]"
安全需求质量： security.md
示例项目：
- "是否为所有受保护资源指定了认证需求？ [覆盖度]"
- "敏感信息的数据保护需求是否已定义？ [完整性]"
- "威胁模型是否已文档化且需求与其对齐？ [可追溯性]"
- "安全需求是否与合规义务一致？ [一致性]"
- "安全失败/违规响应需求是否已定义？ [缺口, 异常流程]"
反例：不要做什么
❌ 错误 - 这些测试实现，而非需求：
- [ ] CHK001 - 验证登录页显示 3 个剧集卡片 [规格 §FR-001]
- [ ] CHK002 - 测试桌面端悬停状态是否正常工作 [规格 §FR-003]
- [ ] CHK003 - 确认 logo 点击导航到首页 [规格 §FR-010]
- [ ] CHK004 - 检查相关剧集部分显示 3-5 个项目 [规格 §FR-005]
✅ 正确 - 这些测试需求质量：
- [ ] CHK001 - 是否明确指定了精选剧集的数量和布局？ [完整性, 规格 §FR-001]
- [ ] CHK002 - 所有交互元素的悬停状态需求是否一致定义？ [一致性, 规格 §FR-003]
- [ ] CHK003 - 所有可点击品牌元素的导航需求是否清晰？ [清晰度, 规格 §FR-010]
- [ ] CHK004 - 相关剧集的选择标准是否已文档化？ [缺口, 规格 §FR-005]
- [ ] CHK005 - 是否为异步剧集数据定义了加载状态需求？ [缺口]
- [ ] CHK006 - "视觉层次"需求是否可以客观衡量？ [可衡量性, 规格 §FR-001]
