EmailBill/.opencode/skills/openspec-verify-change/SKILL.cn.md

name, description, license, compatibility, metadata

name	description	license	compatibility	metadata
openspec-verify-change	Verify implementation matches change artifacts. Use when the user wants to validate that implementation is complete, correct, and coherent before archiving.	MIT	Requires openspec CLI.	author version generatedBy openspec 1.0 1.1.1

验证实现是否与变更 artifacts (specs、tasks、design) 匹配。

输入: 可选择指定变更名称。如果省略,检查是否可以从对话上下文中推断。如果模糊或不明确,你必须提示可用的变更。

步骤

1. 如果未提供变更名称,提示用户选择

   运行 openspec list --json 获取可用的变更。使用 AskUserQuestion 工具让用户选择。

   显示具有实现任务的变更 (tasks artifact 存在)。 如果可用,包含每个变更使用的 schema。 将具有未完成任务的变更标记为 "(进行中)"。

   重要: 不要猜测或自动选择变更。始终让用户选择。

2. 检查状态以了解 schema

   openspec status --change "<name>" --json
   

   解析 JSON 以了解:

   • schemaName: 正在使用的工作流 (例如: "spec-driven")
   • 此变更存在哪些 artifacts

3. 获取变更目录并加载 artifacts

   openspec instructions apply --change "<name>" --json
   

   这将返回变更目录和上下文文件。从 contextFiles 读取所有可用的 artifacts。

4. 初始化验证报告结构

   创建具有三个维度的报告结构:

   • 完整性 (Completeness): 跟踪任务和 spec 覆盖率
   • 正确性 (Correctness): 跟踪需求实现和场景覆盖
   • 一致性 (Coherence): 跟踪设计遵循情况和模式一致性

   每个维度可以有 CRITICAL、WARNING 或 SUGGESTION 问题。

5. 验证完整性

   任务完成度:

   • 如果 contextFiles 中存在 tasks.md,读取它
   • 解析复选框: - [ ] (未完成) vs - [x] (已完成)
   • 统计已完成任务 vs 总任务数
   • 如果存在未完成的任务:
     • 为每个未完成的任务添加 CRITICAL 问题
     • 建议: "完成任务: <描述>" 或 "如果已实现请标记为完成"

   Spec 覆盖率:

   • 如果 openspec/changes/<name>/specs/ 中存在 delta specs:
     • 提取所有需求 (标记为 "### Requirement:")
     • 对于每个需求:
       • 在代码库中搜索与需求相关的关键字
       • 评估实现是否可能存在
     • 如果需求看起来未实现:
       • 添加 CRITICAL 问题: "未找到需求: <需求名称>"
       • 建议: "实现需求 X: <描述>"

6. 验证正确性

   需求实现映射:

   • 对于 delta specs 中的每个需求:
     • 在代码库中搜索实现证据
     • 如果找到,记录文件路径和行范围
     • 评估实现是否符合需求意图
     • 如果检测到偏差:
       • 添加 WARNING: "实现可能偏离 spec: <详情>"
       • 建议: "根据需求 X 审查 :"

   场景覆盖:

   • 对于 delta specs 中的每个场景 (标记为 "#### Scenario:"):
     • 检查代码中是否处理了条件
     • 检查是否存在覆盖该场景的测试
     • 如果场景看起来未覆盖:
       • 添加 WARNING: "场景未覆盖: <场景名称>"
       • 建议: "为场景添加测试或实现: <描述>"

7. 验证一致性

   设计遵循:

   • 如果 contextFiles 中存在 design.md:
     • 提取关键决策 (查找类似 "Decision:", "Approach:", "Architecture:" 的部分)
     • 验证实现是否遵循这些决策
     • 如果检测到矛盾:
       • 添加 WARNING: "未遵循设计决策: <决策>"
       • 建议: "更新实现或修订 design.md 以匹配实际情况"
   • 如果没有 design.md: 跳过设计遵循检查,注明 "没有 design.md 可供验证"

   代码模式一致性:

   • 审查新代码与项目模式的一致性
   • 检查文件命名、目录结构、编码风格
   • 如果发现重大偏差:
     • 添加 SUGGESTION: "代码模式偏差: <详情>"
     • 建议: "考虑遵循项目模式: <示例>"

8. 生成验证报告

   总结记分卡:

   ## 验证报告: <change-name>
   
   ### 总结
   | 维度       | 状态              |
   |-----------|-------------------|
   | 完整性     | X/Y 任务, N 需求   |
   | 正确性     | M/N 需求已覆盖     |
   | 一致性     | 已遵循/有问题      |
   

   按优先级分类的问题:

   1. CRITICAL (归档前必须修复):

      • 未完成的任务
      • 缺失的需求实现
      • 每个都有具体、可操作的建议

   2. WARNING (应该修复):

      • Spec/design 偏差
      • 缺失的场景覆盖
      • 每个都有具体建议

   3. SUGGESTION (最好修复):

      • 模式不一致
      • 小改进
      • 每个都有具体建议

   最终评估:

   • 如果有 CRITICAL 问题: "发现 X 个关键问题。归档前请修复。"
   • 如果只有警告: "无关键问题。有 Y 个警告需要考虑。准备归档 (带注明的改进)。"
   • 如果全部通过: "所有检查通过。准备归档。"

验证启发式方法

• 完整性: 专注于客观的检查清单项 (复选框、需求列表)
• 正确性: 使用关键字搜索、文件路径分析、合理推断 - 不要求完全确定
• 一致性: 寻找明显的不一致,不要挑剔风格
• 误报: 如果不确定,优先选择 SUGGESTION 而不是 WARNING,WARNING 而不是 CRITICAL
• 可操作性: 每个问题都必须有具体的建议,并在适用时提供文件/行引用

优雅降级

• 如果只存在 tasks.md: 仅验证任务完成度,跳过 spec/design 检查
• 如果 tasks + specs 存在: 验证完整性和正确性,跳过 design
• 如果完整 artifacts 存在: 验证所有三个维度
• 始终注明跳过了哪些检查以及原因

输出格式

使用清晰的 markdown:

• 总结记分卡使用表格
• 问题分组列表 (CRITICAL/WARNING/SUGGESTION)
• 代码引用格式: file.ts:123
• 具体、可操作的建议
• 不要使用模糊的建议如 "考虑审查"