checklist

name	checklist
description	根据用户需求为当前功能生成自定义检查清单。
disable-model-invocation	true
allowed-tools	["Bash(node */check-prerequisites.mjs*)"]

检查清单目的："英文的单元测试"

关键概念：检查清单是需求编写的单元测试——它们验证给定领域中需求的质量、清晰度和完整性。

不是用于验证/测试：

• ❌ 不是 "验证按钮点击正确"
• ❌ 不是 "测试错误处理是否工作"
• ❌ 不是 "确认 API 返回 200"
• ❌ 不是检查代码/实现是否匹配规格

用于需求质量验证：

• ✅ "是否为所有卡片类型定义了视觉层次需求？"（完整性）
• ✅ "'突出显示'是否用具体的尺寸/位置量化？"（清晰度）
• ✅ "所有交互元素的悬停状态需求是否一致？"（一致性）
• ✅ "是否定义了键盘导航的无障碍需求？"（覆盖度）
• ✅ "规格是否定义了 logo 图片加载失败时会发生什么？"（边界情况）

隐喻：如果你的规格是用英文编写的代码，检查清单就是它的单元测试套件。你在测试需求是否编写良好、完整、无歧义且准备好实现——不是测试实现是否工作。

用户输入

$ARGUMENTS

你必须在继续之前考虑用户输入（如果不为空）。

执行步骤

1. 设置：从仓库根目录运行 node ${WAVE_PLUGIN_ROOT}/scripts/check-prerequisites.mjs --json 并解析 JSON 获取 FEATURE_DIR 和 AVAILABLE_DOCS 列表。

   • 所有文件路径必须是绝对路径。
   • 对于参数中的单引号如 "I'm Groot"，使用转义语法：例如 'I'''m Groot'（或尽可能使用双引号："I'm Groot"）。

2. 明确意图（动态）：派生最多三个初始上下文澄清问题（无预制目录）。它们必须：

   • 从用户的措辞 + 规格/计划/任务中提取的信号生成
   • 仅询问实质性改变检查清单内容的信息
   • 如果 $ARGUMENTS 中已经明确则单独跳过
   • 优先精度而非广度

   生成算法：

   1. 提取信号：功能领域关键词（例如 auth、延迟、UX、API）、风险指标（"关键"、"必须"、"合规"）、利益相关者提示（"QA"、"审查"、"安全团队"）和明确交付物（"a11y"、"回滚"、"契约"）。
   2. 将信号聚类为候选焦点区域（最多 4 个）按相关性排名。
   3. 识别可能的受众和时机（作者、审查者、QA、发布）如果不明确。
   4. 检测缺失维度：范围广度、深度/严谨性、风险强调、排除边界、可衡量的验收标准。
   5. 从这些原型中选择制定问题：
      • 范围细化（例如，"这应该包括与 X 和 Y 的集成触点还是仅限于本地模块正确性？"）
      • 风险优先级（例如，"这些潜在风险区域中哪些应该接受强制性门禁检查？"）
      • 深度校准（例如，"这是轻量级的提交前健全性列表还是正式的发布门禁？"）
      • 受众框架（例如，"这将仅由作者使用还是在 PR 审查期间由同行使用？"）
      • 边界排除（例如，"我们应该在这一轮明确排除性能调优项目吗？"）
      • 场景类缺口（例如，"未检测到恢复流程——回滚/部分失败路径在范围内吗？"）

   问题格式规则：

   • 如果提供选项，生成带有列的紧凑表格：选项 | 候选 | 为何重要
   • 限制最多 A-E 选项；如果自由格式答案更清晰则省略表格
   • 永远不要要求用户重述他们已经说过的内容
   • 避免推测性类别（不臆造）。如不确定，明确询问："确认 X 是否属于范围内。"

   无法交互时的默认值：

   • 深度：标准
   • 受众：审查者（PR）如果与代码相关；否则为作者
   • 焦点：前 2 个相关性聚类

   输出问题（标记 Q1/Q2/Q3）。回答后：如果 >=2 个场景类（替代/异常/恢复/非功能领域）仍不清楚，你可以再问最多两个有针对性的后续问题（Q4/Q5），每个有一行理由（例如，"未解决的恢复路径风险"）。不超过总共五个问题。如果用户明确拒绝更多则跳过升级。

3. 理解用户请求：结合 $ARGUMENTS + 澄清答案：

   • 派生检查清单主题（例如安全、审查、部署、ux）
   • 合并用户提到的明确必需项目
   • 将焦点选择映射到类别脚手架
   • 从规格/计划/任务推断任何缺失上下文（不要臆造）

4. 加载功能上下文：从 FEATURE_DIR 读取：

   • spec.md：功能需求和范围
   • plan.md（如存在）：技术细节、依赖
   • tasks.md（如存在）：实现任务

   上下文加载策略：

   • 仅加载与活动焦点区域相关的必要部分（避免全文件转储）
   • 优先将长章节总结为简洁的场景/需求要点
   • 使用渐进式披露：仅在检测到缺口时添加后续检索
   • 如果源文档很大，生成临时摘要项目而非嵌入原始文本

5. 生成检查清单 - 创建"需求的单元测试"：

   • 如果不存在则创建 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] 之间的需求是否一致？"
   • ✅ "[需求] 是否可以客观衡量/验证？"
   • ✅ "需求中是否已处理 [边界情况/场景]？"
   • ✅ "规格是否定义了 [缺失方面]？"

6. 结构参考：按照 ${WAVE_PLUGIN_ROOT}/templates/checklist-template.md 中的规范模板生成检查清单，用于标题、元信息章节、类别标题和 ID 格式。如果模板不可用，使用：H1 标题、目的/创建元信息行、包含 - [ ] CHK### <需求项目> 行的 ## 类别章节，ID 从 CHK001 开始全局递增。

7. 报告：输出创建的检查清单完整路径、项目计数，并提醒用户每次运行创建一个新文件。总结：

   • 选择的焦点区域
   • 深度级别
   • 参与者/时机
   • 合并的任何用户指定必需项目

重要：每次 /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]