---
name: grounded-planning
description: "知识驱动的实施计划。基于 DeepWiki 知识和 ToT 推理，将设计方案转化为可执行的分步实施计划。"
---

# 知识驱动的实施计划

本技能用于在 **已通过评审或用户明确批准的设计方案** 基础上，结合项目 `.deepwiki/` 中的架构、技术栈与代码结构知识，并运用 **Tree of Thoughts（ToT）** 多路径推理，产出 **可执行、可验证、可追溯** 的分步实施计划。

**不适用**：尚无稳定设计结论、需求仍在剧烈变动、或 `.deepwiki/` 明显缺失/过期且未补救的场景——请先完成 `grounded-knowledge-prepare` 与 `grounded-brainstorming`，再进入本技能。

**产出物**：一份符合 `templates/planning-output.md` 结构的实施计划文档（Markdown），可直接交给实现会话或人类开发者逐步执行。

---

## 协议引用

执行本技能时，必须同时遵守并交叉引用以下协议（相对路径均相对于 `grounded_workflows` 仓库根或已安装 skill 包的根目录）：

| 协议 | 路径 | 在本技能中的作用 |
|------|------|------------------|
| 上下文构建 | `protocols/context-building.md` | 从 `.deepwiki/` 按需加载与「实施」相关的页面，控制上下文规模与相关性 |
| 知识优先级与标注 | `protocols/grounding.md` | 所有结论与建议必须带 `[DW]` / `[SRC]` / `[EXT]` 标签并满足扩展门控 |
| ToT 结构化推理 | `protocols/tot-reasoning.md` | 对实施顺序、技术路径、依赖与风险做多路径生成→展开→评估→筛选 |

---

## Checklist

智能体须 **按顺序** 完成下列 7 步；不得跳过「知识就绪检查」直接通读页面，也不得在未完成 ToT 分析前输出最终计划正文。

1. **知识就绪检查**  
   - 确认工作区根目录下存在 `.deepwiki/`，且至少包含 `README.md`、`_outline.md` 与若干 `pages/*.md`。  
   - 若目录不存在、明显为空、或 `README.md` / `_outline.md` 表明知识库已严重过期：停止规划，明确告知用户先执行 **`grounded-knowledge-prepare`**（或重新生成 / 同步 DeepWiki），并列出缺失项。  
   - 若就绪：记录知识库版本说明（若有）与检查时间，作为计划文档元信息的一部分。

2. **加载知识**  
   - 严格按 `protocols/context-building.md` 的五步流程：先读 `.deepwiki/README.md` 与 `_outline.md`，再按任务关键词从 `pages/*.md` 中 **选择性加载**。  
   - **规划阶段优先关注**（在关键词匹配时提高权重）：整体架构、模块边界、技术栈与运行时、目录/包结构与分层约定、与本次改动相关的子系统或数据流页面。  
   - 将抽取结果整理为带 `[DW]` 前缀的结构化块，供后续文件规划与 ToT 使用；遵守「单次 2～5 页、常规 3 页以内」的规模指导。

3. **读取设计输入**  
   - 向用户确认 **头脑风暴或设计评审输出文档** 的路径（例如 `docs/.../brainstorming-output.md`）；若用户已在当前会话中粘贴了等价内容，可将「会话内设计摘要」视为输入，但须在计划头中注明「无独立文件，摘要来自会话」。  
   - 完整阅读该文档中的目标、约束、方案对比与 **已选定方案**；禁止在计划中正向引入设计文档未包含的新需求，除非用户显式补充并标注为变更。  
   - 若设计输入缺失：列出为完成规划所必需的最低信息清单，请用户补充后再继续。

4. **文件结构规划**  
   - 基于上一步 `[DW]` 中的 **项目结构、分层与命名约定**，列出本次实施需 **新建** 与 **修改** 的文件清单。  
   - 每个文件一行说明其在方案中的职责（一句话）；对删除或重命名类操作单独标注风险与回滚提示。  
   - 若 `[DW]` 与 `[SRC]` 对同一事实不一致：以 `protocols/grounding.md` 为准仲裁，并在计划中写明「以源码为准」或「建议同步更新文档」的结论。

5. **ToT 实施路径分析**  
   - 严格遵循 `protocols/tot-reasoning.md`：针对「实施顺序、接口切分、渐进式 vs 一次性、测试与发布节奏」等 **高影响决策点**，至少生成 **3 条可区分方向**，完成展开、统一维度评估与筛选。  
   - 分析维度须显式包含：**任务间依赖**（哪些步骤阻塞后续）、**对外部系统/配置的顺序要求**、**可并行工作包**、**验证成本**（何阶段运行何种测试最划算）。  
   - 每条路径中的断言须带 `[DW]` / `[SRC]` / `[EXT]` 及引用或门控说明，避免无标签的「经验排序」。

6. **生成分步计划**  
   - 在选定主路径下，将工作拆解为 **粒度足够小** 的步骤：每步应能由单次 focused 变更或短会话完成，并具备 **独立可验证** 的完成标准。  
   - **书写格式**：使用 Markdown 复选框（`- [ ]`），每步至少包含子项：**具体动作**、**涉及文件**（使用仓库内真实相对路径，禁止 `path/to/...` 式占位）、**预期结果**、**验证方法**（具体命令、断言或检查步骤）。  
   - **依赖标注**：在步骤标题或紧接一行用 `依赖：Step X` 或 `依赖：Task A Step 2` 等形式标明前置条件；无依赖的可标 `依赖：无`。  
   - **顺序原则**：优先安排 **数据模型、迁移、配置、环境变量、构建/CI 契约** 等基础设施，再安排业务逻辑、UI 与集成；测试与文档步骤与实现步骤对齐，避免「先写大量无测代码再补测」。

7. **输出计划**  
   - 将上述内容整理为 **`templates/planning-output.md` 所定义的完整章节结构**：知识上下文、文件结构表、ToT 分析、任务分解（含复选框步骤）、验证清单。  
   - 填充模板中的日期、设计来源路径、`.deepwiki` 路径与 **来源统计**（`[DW]` / `[SRC]` / `[EXT]` 条数或等价度量），并确保 `[EXT]` 占比与项目 grounding 阈值一致或在文中说明例外理由。  
   - 向用户交付最终 Markdown：可写入用户指定路径，或由用户复制到仓库 `docs/` 下；文件名建议包含功能slug与 `planning` 字样以便检索。

---

## 计划粒度指导

- **步骤大小**：宁可「多步小步」，也不要单步混合多个不相关 concern；若一步同时改多个模块，应拆分为「接口契约 → 各实现 → 集成」序列。  
- **路径精确性**：所有「涉及文件」须为相对仓库根的真实路径（与 `grounding.md` 引用格式一致）；若尚不存在的新文件，使用拟定完整路径并注明「新建」。  
- **验证闭环**：每步必须有可操作的验证手段——单元测试命令、类型检查、linter、手工 API 调用步骤、或「阅读 diff 确认无无关变更」等；禁止仅写「完成开发」。  
- **依赖显式化**：依赖链应能从文中直接画出；禁止隐含顺序（例如配置未就绪即部署业务）。  
- **分层优先级**：基础设施与横切关注点（鉴权、日志、错误码、观测性）优先于具体业务分支，除非设计文档明确要求例外并给出风险缓释。

---

## 流程图

```mermaid
graph TD
    Start[用户调用 planning] --> Check[知识就绪检查]
    Check -->|未就绪| KP[引导使用 grounded-knowledge-prepare]
    Check -->|就绪| Load[加载知识：架构+技术栈+代码结构]
    Load --> Design[读取设计输入]
    Design --> Files[文件结构规划]
    Files --> ToT[ToT 实施路径分析]
    ToT --> Plan[生成分步计划]
    Plan --> Output[输出计划文档]
```

---

## 工具映射

下表说明本技能各阶段与 **典型智能体工具能力** 的对应关系（具体工具名随平台而变，语义等价即可）。

| 工作流阶段 | 主要动作 | 推荐工具/能力 | 备注 |
|------------|----------|----------------|------|
| 知识就绪检查 | 列目录、探测 `.deepwiki` 关键文件是否存在 | 文件系统列举、最小化 `Read` 抽样 | 未就绪则短路退出并提示 `grounded-knowledge-prepare` |
| 加载知识 | 读 README、大纲、按需读 pages | `Read`、必要时 `Grep` / 语义搜索 | 严格遵守 context-building 页数上限 |
| 读取设计输入 | 读取用户给定路径下的设计文档 | `Read` | 路径必须由用户确认；大文件可分段读取 |
| 文件结构规划 | 对照 `[DW]` 目录约定，核对源码树 | `Read`、`Grep`、代码搜索 | 结构冲突时回到 `[SRC]` 校验 |
| ToT 实施路径分析 | 多路径推理与评分 | 无专用工具：在对话中按 `tot-reasoning.md` 骨架输出 | 产出写入计划 §3 |
| 生成分步计划 | 勾选式任务列表、依赖边 | 结构化 Markdown 编辑 | 与模板 §4 对齐 |
| 输出计划 | 套用模板、写文件 | `Write` / `StrReplace` 或等价写入 | 默认使用 `templates/planning-output.md` |

---

## 质量门禁（输出前自检）

- [ ] 计划全文结构与 `templates/planning-output.md` 一致，无遗漏章节。  
- [ ] 所有关键断言具备 `grounding.md` 要求的标签与引用或 `[EXT]` 门控说明。  
- [ ] ToT 部分不少于 3 个方向且已完成评估与单一主路径（或经批准的合成方案）结论。  
- [ ] 每步含：**动作、文件、预期结果、验证方法、依赖**；文件路径无占位符。  
- [ ] 来源统计与验证清单已填写，**`[EXT]` 占比**符合项目约定或已解释偏差原因。

完成以上自检后，方可将文档视为 **可交付实施计划**。