spec-driven-verify

你正在帮助用户在归档前验证规范驱动的变更。

此技能的命令

如果你不记得此技能使用的确切命令，请在运行任何命令之前在此查找。 不要猜测。

modify: node {{SKILL_DIR}}/scripts/spec-driven.js modify
verify: node {{SKILL_DIR}}/scripts/spec-driven.js verify <name>
verify-spec-mappings: node {{SKILL_DIR}}/scripts/spec-driven.js verify-spec-mappings
apply: node {{SKILL_DIR}}/scripts/spec-driven.js apply <name>
audit-spec-mapping-coverage: node {{SKILL_DIR}}/scripts/spec-driven.js audit-spec-mapping-coverage <spec-path> [--implementation <repo-path> ...] [--tests <repo-path> ...]
audit-unmapped-spec-evidence: node {{SKILL_DIR}}/scripts/spec-driven.js audit-unmapped-spec-evidence [--implementation <repo-path> ...] [--tests <repo-path> ...]

前置条件

.spec-driven/ 目录必须位于项目根目录。继续之前，请验证：

ls .spec-driven/

如果验证失败，说明项目尚未初始化。请先运行 /spec-driven-init。

步骤

1. 选择变更 — 运行 node {{SKILL_DIR}}/scripts/spec-driven.js modify 列出活动变更。询问要验证哪项变更。如果已指定，则使用该变更。

2. 格式检查 — 运行：

   node {{SKILL_DIR}}/scripts/spec-driven.js verify <name>
   

   报告所有错误（阻塞性）或警告（非阻塞性）。

   • 将脚本报告的任何测试准备情况错误视为严重问题，包括缺少 ## Testing、缺少 lint/验证覆盖、缺少单元测试覆盖，或必需的测试任务没有明确可运行的命令。

   还要运行：

   node {{SKILL_DIR}}/scripts/spec-driven.js verify-spec-mappings
   

   将格式错误的规范映射 frontmatter、缺少映射字段或缺少映射文件视为相关主规范的严重问题。

3. 任务完成情况检查 — 运行：

   node {{SKILL_DIR}}/scripts/spec-driven.js apply <name>
   

   如果 remaining > 0，请列出未完成的任务。这些是严重问题。

4. 未解决问题检查 — 阅读 .spec-driven/changes/<name>/questions.md，并查找 - [ ] Q: 条目：

   • 任何未解决的问题都是严重问题
   • 脚本也会将这些问题报告为错误；在此处应将其视为严重问题

5. 实现证据检查 — 对于 tasks.md 中每个已完成的任务：

   • 确认该任务应该修改哪些代码或文件
   • 验证相应变更确实存在（阅读相关文件）
   • 如果已完成的任务声称完成了实现、测试或规范工作，但没有可见证据，则应视为严重问题，除非 questions.md 中清楚记录了相关情况

6. 构建映射证据集 — 在评估映射质量之前，先从以下内容构建仅针对当前变更的证据集：

   • .spec-driven/changes/<name>/specs/ 下每个已变更的增量规范文件
   • 实际为已完成行为所做修改的实现文件
   • 实际为已完成行为所做修改的测试文件
   • 明确依赖来提供或直接验证已完成行为的文件

   尽量使用范围最小且可信的证据集。当主实现文件或直接测试文件已明确时，不要从关联较远的辅助文件推断语义覆盖情况。

   对每个已变更的增量规范文件，运行：

   node {{SKILL_DIR}}/scripts/spec-driven.js audit-spec-mapping-coverage <spec-path> [--implementation <repo-path> ...] [--tests <repo-path> ...]
   

   使用构建的证据集作为明确的 --implementation 和 --tests 输入。

   还要运行：

   node {{SKILL_DIR}}/scripts/spec-driven.js audit-unmapped-spec-evidence [--implementation <repo-path> ...] [--tests <repo-path> ...]
   

   使用同一证据集，找出未映射到任何主规范的实现文件或测试文件。

7. 规范对齐检查 — 阅读 .spec-driven/specs/、.spec-driven/config.yaml、.spec-driven/changes/<name>/proposal.md，以及 .spec-driven/changes/<name>/specs/ 中的所有文件：

   • 实现是否符合提案内容？
   • changes/<name>/specs/ 中的增量文件是否准确描述了已实现的内容？如果 specs/ 为空，但行为确实发生了变化，则属于 CRITICAL。
   • 每个增量文件是否与对应的主规范文件路径一致？路径不匹配会导致合并失败。
   • 增量文件是否采用标准格式（### Requirement: <name>、RFC 2119 关键词、#### Scenario: 块）？格式不合规属于 CRITICAL — 规范格式为强制要求。
   • 对每个已修改的增量规范文件，使用以下审计输出，将 mapping.implementation 和 mapping.tests 与此变更范围内的证据集进行比较： node {{SKILL_DIR}}/scripts/spec-driven.js audit-spec-mapping-coverage <spec-path> [--implementation <repo-path> ...] [--tests <repo-path> ...]。
   • 如果证据明确表明某个已修改的规范依赖某个实现文件或直接验证该规范的测试文件，但映射中缺少该文件，则将此遗漏报告为 CRITICAL。
   • 如果证据存在歧义，应优先采用范围较小且有充分把握的集合，并报告歧义，而不是臆造语义覆盖关系。
   • 使用 node {{SKILL_DIR}}/scripts/spec-driven.js verify-spec-mappings 的结果，单独报告仓库范围内的结构性映射错误，不要与变更范围内的映射遗漏混为一谈。
   • 如果未映射证据审计显示，此变更中的主要实现文件或直接验证该实现的测试文件未映射到任何主规范，且该缺口导致此变更的规范覆盖不完整，则报告为 CRITICAL。
   • 如果未映射证据审计仅发现此变更范围之外的文件或关联较弱的候选项，应将其单独报告为 REPO DEBT 或低置信度的 WARNING。
   • 如果 config.yaml 有 rules 字段（包括任何 fileMatch 条目），请检查实现和产物是否符合规则 — 违规属于 WARNING。
   • 如果 proposal.md 中有包含内容的 Unchanged Behavior 章节，请验证实现是否违反了其中列出的任何行为 — 违规属于 CRITICAL。
   • 将不一致项标记为 WARNING 或 CRITICAL。

8. 输出分级报告：

   CRITICAL（阻止归档）：
     - [列表或“无”]
   
   REPO DEBT（此变更范围之外）：
     - [列表或“无”]
   
   WARNING（应处理）：
     - [列表或“无”]
   
   SUGGESTION（可选改进）：
     - [列表或“无”]
   

9. 建议后续步骤：

   • 如果存在 CRITICAL 问题：归档前先解决
   • 如果只有 WARNING：询问用户是要处理这些问题还是继续
   • 如果没有问题：建议运行 /spec-driven-review <name>

规则

• 如实评估 — 不要仅仅因为任务已勾选就判定变更合格
• CRITICAL 指会导致变更错误或不完整的问题
• REPO DEBT 指变更范围之外的既有仓库问题；应清晰报告，并与变更范围内的发现分开
• WARNING 指会降低可信度但不一定会阻止流程的问题
• SUGGESTION 指可选的质量改进
• 将实现和测试映射放在 frontmatter 中，而不是需求正文中