skills/cc-switch-dev-workflow/references/knowledge-base/playbooks/spec-code-alignment-gap-closure.md

Playbook: Spec-Code Alignment Gap Closure

Purpose

当 SPECS/*.md 已经存在，但代码与规范发生漂移时，用最短路径恢复一致性。

When to Use

• 已有 Spec
• 代码和 Spec 明显不一致
• 验收前发现遗漏、偏离或未测试条款

Inputs

• SPECS/*.md
• 现有代码
• 当前测试结果
• 既有 .plans/*.md

Outputs

• Gap ANALYSIS.md
• Alignment TODO.yaml
• 补齐计划与补齐实现
• 验收前复核结论

Primary Agent/Model

计划/实现 agent + GPT-5.4 Pro xhigh

Secondary Agent/Model

审查 agent + Claude Opus 4.6

Required Skills

• spec-gap-analyzing
• spec-gap-tasking
• tdd-planning
• tdd-implementing
• code-simplifying
• code-refactoring

Steps

1. 先做 Gap 分析，分类为 Missing / Partial / Divergent / Untested / Integration。
2. 基于分析生成 Plan/Impl 对。
3. 按优先级补齐高风险缺口。
4. 每批缺口后做简化和重构。
5. 重新跑验收清单。

Exit Criteria

• 已知高优先级缺口全部收敛
• Spec 与代码重新建立可验证的一致性

Failure Recovery

• 如果发现问题源头是 Spec 错误，回到 Spec 阶段修订
• 如果缺口范围不断扩大，回到计划层重排优先级

Related Templates

• ../templates/tdd-plan-template.md
• ../templates/todo-yaml-template.md
• ../templates/acceptance-checklist-template.md

Stable Knowledge Vs Runtime Context

• 稳定知识：Gap 分类、Plan/Impl 对、检查点机制
• 运行时上下文：本轮缺口证据、本轮实现状态、本轮测试失败点

First-Round Prompt Kit

Prompt 1: Gap Analysis

基于 SPECS/*.md 和当前代码，生成 Gap ANALYSIS.md。逐条指出 Missing、Partial、Divergent、Untested、Integration 五类问题，并按影响优先级排序。

Prompt 2: Gap Tasking

基于已审核的 Gap ANALYSIS.md 和 SPECS/*.md，生成 Alignment TODO.yaml。每个真实缺口都拆成 Plan/Impl 对，并按批次插入 Simplify/Refactor 检查点。

Prompt 3: Closure

按 TODO.yaml 补齐缺口。每个 Impl 任务后立即简化，批次后做重构；最后输出剩余风险、未覆盖项和再次验收建议。

Stage Deliverables

• Gap 分析：ANALYSIS.md
• Gap 任务：TODO.yaml
• 实施计划：.plans/*.md
• 补齐后代码与测试
• 验收前复核说明

Acceptance Checklist

• 五类缺口均已分类处理
• 没有用“更优雅实现”替代对 Spec 的遵守
• 关键流程已有测试托底