# 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/tdd-plan-template.md)
- [`../templates/todo-yaml-template.md`](../templates/todo-yaml-template.md)
- [`../templates/acceptance-checklist-template.md`](../templates/acceptance-checklist-template.md)

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

## First-Round Prompt Kit

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

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

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

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

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