---
name: plan-to-spec
description: 将 Plan Mode 的讨论结论固化为可执行的 Markdown 施工图纸。当用户完成 Plan 讨论、准备进入开发阶段时使用。生成 overview.md（战略层）、taskXX_*.md（战术层）、summary.md（审计层）三类文档，实现上下文序列化，避免 Plan 与 Code 偏航。
---

# Plan-to-Spec：上下文固化与施工图生成

## Overview

本 skill 扮演"施工监理"角色，**不写代码**，只将 Plan Mode 的讨论结论固化为可执行的 Markdown 施工图纸。核心目标是**上下文序列化（Context Serialization）**：将短期对话记忆转录为长期存储文档，作为后续开发（同会话/新会话/Subagent）的**唯一可信输入**。

## 何时使用这个 Skill

**触发时机**：
- 用户确认 Plan 已完成，准备进入开发阶段
- 需要将讨论的架构设计、技术方案固化为文档
- 需要为后续开发提供清晰的施工指南

**典型场景**：
```
用户："Plan 讨论完成了，现在帮我生成施工图文档"
用户："把我们刚才讨论的方案整理成开发文档"
用户："准备开始开发，先把任务文档生成好"
```

**不适用场景**：
- 直接开发代码（应该先生成文档，再开发）
- Plan 尚未完成或方案不明确
- 简单的单文件修改（无需完整施工图）

## 核心设计哲学

### 1. 上下文序列化
将短期对话记忆转录为长期存储文档，确保：
- 新接手的 Agent 只看文档就能推进开发
- 不依赖回看聊天记录
- 上下文解耦、自包含

### 2. 三层文档架构
- **战略层（overview.md）**：架构总览、目标、影响面、任务索引
- **战术层（taskXX_*.md）**：可执行的施工单，每个 step 独立闭环
- **审计层（summary.md）**：验收框架，开发中逐步填写

### 3. 关键约束
- **禁止直接编码**：本阶段只产出 `.md` 文档
- **禁止编造需求/结论**：不确定的信息写 `TODO/待确认`
- **禁止完整实现体**：技术方案只写流程/算法/策略，不写完整代码

## 核心工作流程

### 阶段一：初始化与结构确立

1. **确认任务名称**：询问用户任务名称（如 `pseudo_section_builder`）
2. **创建目录结构**：在 `docs/dev_notes/{task_name}/` 创建目录
3. **生成文件清单**：一次性列出所有要生成的文件（路径 + 用途）
   - `overview.md` - 战略层全景图
   - `task01_{subtask}.md`, `task02_{subtask}.md`, ... - 战术层施工单
   - `summary.md` - 审计层验收单

**目的**：避免边写边改结构导致遗漏、重复、漂移。

### 阶段二：逐一填充文档内容

按照以下顺序生成文档：

1. **生成 overview.md**（战略层）
   - 基于 Plan 讨论内容填充
   - 必须包含：通俗摘要、目标/非目标、现状与约束、目标架构树、关键类型/接口、影响面清单、任务索引
   - **禁止**：具体实现代码、完整类实现

2. **生成 taskXX_{subtask}.md**（战术层）
   - 将 Plan 分解为独立的可执行步骤
   - 每个 task 文件对应一个最小闭环的施工单
   - 必须包含：通俗摘要、本步目标、范围、变更清单、技术方案、本步契约、验证、DoD
   - **禁止**：完整实现体

3. **生成 summary.md**（审计层）
   - **仅搭建框架**，所有正文内容以 `TODO` 占位
   - 不填写任何事实性内容（避免编造未发生的交付/验证结果）
   - 开发过程中逐步更新

### 阶段三：交付确认

生成完成后，输出施工图绘制完成报告：

```
✅ 施工图绘制完成

已在 `docs/dev_notes/{task_name}/` 生成施工图文档：
1. overview.md - 架构总览与任务索引
2. task01_{...}.md - 待执行
3. task02_{...}.md - 待执行
...
n. summary.md - 验收框架（开发中填写）

请确认后开始执行 task01。
```

## 文档模板说明

本 skill 提供三个文档模板，位于 `references/` 目录：

### 1. overview.md 模板（战略层）

**用途**：架构总览，给人和 Agent 快速建立上下文

**必须包含的章节**：
- **通俗摘要**（3~5句）：为什么做/做成什么/怎么做/影响面
- **目标/非目标**：明确做什么、不做什么
- **现状与约束**：当前状态、痛点、兼容性/性能/依赖约束
- **目标架构树**：
  - 目录/包树（代码落点）
  - 模块职责树（概念落点）
  - 依赖规则（可选）
- **关键类型/接口清单**：仅名称与用途，不写实现
- **影响面清单**：会改动的模块、可能影响的调用方、兼容性注意
- **任务索引**：列出所有 taskXX_*.md 的范围与依赖

**字数控制**：
- 通俗摘要限 3~5 句
- 架构树保持 2~3 层深度
- 清单优先，少段落解释

### 2. taskXX_{subtask}.md 模板（战术层）

**用途**：可执行的施工单，给 Coding Agent 执行

**必须包含的章节**：
- **通俗摘要**（3~5句）：本步做什么/怎么做/产出/影响与风险
- **本步目标**：最小闭环的交付结果
- **范围**：做什么、不做什么
- **变更清单**：文件级变更（add/modify/delete + 目的）
- **技术方案**：流程/算法/策略，3~6 条 bullet，禁止完整实现体
- **本步契约**：只写本步相关的 I/O、边界、错误处理
- **验证**：测试点 + 命令 + 预期
- **本步 DoD**：完成定义检查清单

**字数控制**：
- 技术方案 3~6 条 bullet
- 契约表只写"本步相关"
- 验证写"命令 + 预期"一行到两行

### 3. summary.md 模板（审计层）

**用途**：验收总结框架，开发中逐步填写

**创建时策略**：
- **仅搭建框架**，所有正文内容以 `TODO` 占位
- **禁止填写事实性内容**（避免编造未发生的交付/验证结果）

**包含的章节**：
- 结果（状态、已交付、未交付/延期）
- 变更摘要（新增、修改、移除、破坏性变更）
- 验证证据（单测、其他检查）
- 文档同步（勾选清单）
- 问题与解决
- 后续建议

**填写时机**：开发过程中逐步更新，任务结束时完整填写

## 使用示例

### 示例 1：基础使用流程

```
用户："Plan 讨论完成了，现在帮我生成施工图文档"

Agent（使用 plan-to-spec skill）：
1. 询问任务名称
2. 创建 docs/dev_notes/{task_name}/ 目录
3. 生成文件清单并确认
4. 逐一生成 overview.md、taskXX_*.md、summary.md
5. 输出完成报告

用户："确认，开始执行 task01"
Agent：读取 task01_*.md，按照施工单执行开发
```

### 示例 2：处理不确定信息

```
Plan 讨论中提到："可能需要支持 Redis 缓存，但还没确定"

在 overview.md 中应该写：
- 现状与约束：缓存策略待确认（TODO：确认是否使用 Redis）
- 影响面清单：如启用缓存，需考虑缓存失效策略

在 taskXX.md 中应该写：
- 范围 - 不做：缓存实现（待后续确认）
```

### 示例 3：任务分解

```
Plan 目标：实现伪断面构建功能

分解为 3 个 task：
- task01_data_loader.md：加载电极数据和测量数据
- task02_pseudo_section_builder.md：构建伪断面网格
- task03_visualization.md：可视化输出

每个 task 独立闭环，可单独验证。
```

## 关键规则与约束

### 红线（必须遵守）

1. **禁止直接编码**
   - 本阶段产物只能是 `.md` 文档
   - 若出现写 `.py/.ts` 等实现倾向，必须纠正

2. **禁止编造需求/结论**
   - 不确定的信息必须写 `TODO/待确认`
   - 不允许为了"完成度"而填充看似合理但未经确认的内容

3. **上下文解耦/自包含**
   - 生成的文档必须能让"新接手的 Agent 只看这些文档"就能推进开发
   - 不依赖回看聊天记录

### 决策点规则

- **决策点为可选项**，仅在存在关键取舍时记录
- 何时需要写：架构取舍、兼容策略、性能策略、接口选择、依赖选择
- 没有决策时：写 `N/A` 或直接移除该节

### 可选内容的填写原则

- 标注为「可选」的小节：不要求填写
- 若无信息或无必要：写 `N/A` 或删去该节
- 避免模板驱动的"无意义填充"

## Resources

本 skill 包含以下资源文件：

### references/

包含三个文档模板，用于生成施工图文档：

1. **template_dev_overview.md**
   - 战略层全景图模板
   - 包含：通俗摘要、目标/非目标、现状与约束、目标架构树、关键类型/接口、影响面清单、任务索引
   - 使用时：基于 Plan 讨论内容填充各章节

2. **template_dev_task_subtaskstep.md**
   - 战术层施工单模板
   - 包含：通俗摘要、本步目标、范围、变更清单、技术方案、本步契约、验证、DoD
   - 使用时：为每个独立的开发步骤创建一个 taskXX_*.md 文件

3. **template_dev_task_summary.md**
   - 审计层验收单模板
   - 包含：结果、变更摘要、验证证据、文档同步、问题与解决、后续建议
   - 使用时：创建时仅搭建框架（所有内容为 TODO），开发中逐步填写

### 使用方式

生成文档时，参考这些模板的结构和章节，但不是简单复制粘贴：
- 根据实际 Plan 内容填充
- 不确定的信息写 `TODO/待确认`
- 可选章节可删除或写 `N/A`
- 保持简洁，避免冗余