Plan Track

---
name: plan-track
description: plan 模式执行者：为复杂任务在项目根 .plans/ 建档（plan.md 目标/完成判据/工作项 + checklist.md 自评审清单），执行中按证据更新进度，完成后逐条自评审。触发："列个计划"、"创建计划文档"、"跟踪进度"、"做完自检"、"进入 plan 模式"，或任务多文件/多阶段/需跨会话续做。
---

# 计划与进度跟踪（Plan & Track）

## 概述

**目的**：把复杂任务的执行状态从对话上下文里搬到文件里——**上下文会丢，文件不会**；同时把"完成"从 AI 的自我感觉变成**可勾选、须带证据**的判据。

**功能**：
- 任务开始前在 `.plans/` 建档：`plan.md`（活文档）+ `checklist.md`（自评审清单）
- 建档时提炼**注意事项（执行护栏）**——本任务"过程中不能踩的线"，执行中对照、验收时逐条查
- 执行中按**证据**更新工作项状态，支持中断后续做、跨会话续做
- 任务主体完成后逐条自评审（含护栏遵守情况），P0 未清零不放行
- 完成后收口交接，保留档案作为执行历史

**使用场景**：
- **由 `plan-track` 规则识别场景后调用**（含上游 skill 交接，如 `requirement-mining` 快速实现路径；场景与判据的 SSOT 在规则，本 skill 只负责执行）
- 用户直接说"列个计划"、"创建计划文档"、"跟踪一下进度"、"做完自己评一遍"时
- 任何类型的复杂任务：写代码 / 改配置 / 排查故障 / 数据迁移 / 批量整理文档等；有前置文档顺用其产出，**没有也能用**（现场粗拆工作项）

## 定位

**通用执行台账**：任何"足够复杂、会跨多轮"的任务都可以用——不限定任务类型，也不要求前置文档。

```
任意复杂任务
（用户口头任务 / 需求文档 / 设计文档 / 工作项清单 / Issue / 报错现场 …）
                    ↓
        plan-track（本 skill：建档 → 更新 → 完成后自评审）
                    ↓ 完成后按任务类型**可选**交接
   实现类 → auto-review（审查）→ acceptance-verify（交付验收）→ implementation-report（归档）
   其他类 → auto-review（审查）→ 用户验收 / 自行收尾
```

- **输入**：任何能说清"要做什么"的任务来源——用户口头描述、需求文档、设计文档、工作项清单、Issue、报错现场均可；**没有前置文档也能用**
- **输出**：`.plans/{YYYY-MM-DD}-{任务slug}/plan.md` + `checklist.md`（任何任务类型都是这两份）
- **不绑定上下游**：
  - **上游可选**：任务来自 `use_skill("work-breakdown")` / 设计文档 / 需求文档时，顺用其产出（工作项、验收标准直接转为台账内容）；**没有这些前置时本 skill 独立可用**
  - **下游可选**：收尾交接按任务类型取舍——都先过 `auto-review`，实现类再依次 `acceptance-verify` → `implementation-report`，非实现类由用户验收或自行收尾
- **边界**：
  - 只管**执行期**的计划与进度：不拆工作项（拆分用 `use_skill("work-breakdown")`）、不做技术设计（用 `use_skill("design-craft")`）
  - 自评审是**内部闸门**，**不替代交付验收**——交付验收由 `use_skill("acceptance-verify")` 或用户执行
  - **纯文件操作，不调用任何 MCP / 知识库工具**：计划是高频改写的活文档，直接编辑文件即可

## 核心原则

1. **状态外部化**：进度只认 `plan.md`，不留在对话记忆里；续做的第一个动作永远是读 `plan.md`
2. **证据绑定**：工作项标「已完成」必须附证据（命令+输出 / 文件+行号 / 测试结果）；**已改但未验证只能标「已改未验」**——静态检查 ≠ 已验证
3. **唯一活台账**：一个任务一份计划；已有阶段台账（如骨架的 `skeleton-status.md`）时，把它的内容作为工作项纳入本计划，**不另立平行台账**
4. **闸门客观化**：是否建档由 `plan-track` 规则里的可观测判据决定（SSOT 在规则），不靠"我觉得复不复杂"自评
5. **清单可判定、不可临场放宽**：清单项必须能回答"通过 / 不通过"，禁写"代码优雅""逻辑清晰"这类无法判定的项；**严重度在建档时定死，评审期只能回填不能改题**
6. **轻量优先**：计划是执行工具不是交付物——不追求好看，追求准确、更新得动
7. **不删档**：完成后保留作为执行历史，只改状态不删除
8. **护栏不静默放宽**：注意事项与清单同样**建档时定死**——执行中不得自行删改；不适用须在「决策与偏差」留痕，新发现的护栏须追加并**同步补进清单**（见 Step 1 / Step 2）。**本条是 skill 侧机制，规则的「四条不可妥协」不变、也不要求改规则**

## 执行流程

```
Step 0 触发确认 → Step 1 建档 → Step 2 执行中更新 → Step 3 完成后自评审 → Step 4 收尾（auto-review → acceptance-verify → 归档）
```

### Step 0：触发确认（场景判定）

**"何时进入 plan 模式"的 SSOT 在 `plan-track` 规则**——本 skill **不重复定义场景与判据**（重复定义必然双源漂移）。规则命中后调用本 skill，本 skill 只负责执行。

| 调用来源 | 动作 |
|----------|------|
| 规则命中后调用（常态） | 直接进入 Step 1 |
| 用户直接要求（"列个计划 / 建个清单 / 跟踪进度"） | 直接进入 Step 1 |
| **上游 skill 默认交接**（如 `requirement-mining` 快速实现路径：用户选"直接实现"、跳过设计文档） | 直接进入 Step 1；**下方「不建档」清单同样适用**——上游任务若属单文件小改 / 文案 typo，照常跳过，不因"上游要求"而硬建 |
| **规则不可用**（目标项目未装规则） | 按本 skill description 的触发条件自判：多文件 / 多模块 / 多阶段 / 跨会话 → 建档；**拿不准时建档**（成本几分钟，远低于重做） |

> `description` 只是**检索用的近似触发描述**，判据以 `plan-track` 规则为准——两边**不必逐字同步**，改判据只改规则。

**不建档**（避免形式主义）：单文件小改、文案 / typo 修复、单步问答、纯咨询；用户说"不用建计划"→ 不建（已建档案保留状态、不再更新）。

**边界情形**：任务行进中发现复杂度上升 → **中途补建档**（把已完成的项按证据补录为「已完成」）。

### Step 1：建档

**先查重（防平行台账）**：建档前扫一遍 `.plans/`——若已存在 `status: 进行中` 且与本任务同源（同名 / 同 `related` / 同 slug）的目录，**复用该目录**（在「进度日志」追加一行后续做），**不新建**；仅当任务范围明显不同才新建目录。

**目录与命名**：`{项目根}/.plans/{YYYY-MM-DD}-{任务slug}/`

- 项目根 = 用户指定，未指定则取当前 workspace 根
- slug 用 kebab-case（如 `fix-order-timeout`）
- 目录不存在时创建；**不修改 `.gitignore`**——是否入库由用户自行决定

**两个文件**：

| 文件 | 性质 | 更新频率 |
|------|------|----------|
| `plan.md` | 活文档：目标 / 完成判据 / **注意事项（护栏）** / 工作项+状态+证据 / 决策与偏差 / 日志 | 每完成或阻塞一项即更新 |
| `checklist.md` | 自评审清单：可勾选、每项须填证据；**E 组 = 护栏镜像** | 建档时生成（E 组随护栏生成），任务完成后逐条回填 |

**工作项从哪来**（按优先级；前一条不可用时顺延到后一条）：

1. `use_skill("work-breakdown")` 产出的工作项清单 → 直接转为工作项，保留其"独立验证方式"（**该 skill 不可用则忽略**，顺延第 2 条）
2. 设计文档 / 需求清单（REQ-*，来自 `requirement-mining` 快速实现路径）/ **`code-review` 报告的 P0/P1 表** / 骨架批次 / TODO 清单 → 按"可独立验证"切成工作项（来自 `code-review` 时**只引报告编号与路径，不复制分析内容**——报告是事实源，本台账只存指针与状态）
3. 无前置文档 → 现场粗拆 3-8 项（**粗粒度、垂直可验证**，详细设计不在这里做）

**清单项从哪来（防止"自己出题自己答"）**：`checklist.md` 的条目**必须有外部依据**，来源仅限——① plan.md 的完成判据；② 设计文档 / 需求文档里的验收标准；③ 用户明确提出的要求；④ [reference.md](reference.md) 的任务类型增补表；⑤ `code-review` 报告「检查覆盖表」中的 ❌/⚠️ 项（转成可判定问法，不复制证据）。**不得凭"我打算怎么做"倒推出宽松的题目。**

**建档时定死严重度**（评审期不得改）：

| 级别 | 判定 | 处置 |
|------|------|------|
| **P0（阻断）** | 不通过会产出错误结果 / 数据损坏 / 交付不可用 / 未验证即交付 | 未清零**不放行** |
| **P1（重要）** | 影响可维护性 / 体验 / 有潜在风险，可延后处理 | 记录并交接，不阻断 |

**注意事项（执行护栏）从哪来**（防跑偏的那一节）：

工作项与完成判据回答"做成什么"，护栏回答**"过程中别踩什么"**——它拦的是"每项都标了完成、证据也齐全，但方向已经偏了"这类失败。护栏**一对一**生成清单 E 组，验收时才不会漏检。

**写法三条**（不满足就别写，软提示等于没写）：

| 要求 | 说明 |
|------|------|
| **可判定** | 能回答"守住了 / 没守住"；禁写"注意代码质量""保持一致性"这类无法判定的项 |
| **动作化** | 写清"不要做什么 / 必须做什么"，不写"小心…""尽量…" |
| **带后果** | 「违反后果」列**必须以 `P0：` / `P1：` 开头**（后接一句话后果）——它是 E 组严重度的唯一来源，不写级别则 E 组无从定级 |

**来源**（同清单项，只认外部依据，不得凭"我打算怎么做"倒推）：① 用户明确要求（"别动 X""必须保持 Y"）；② 上游文档约束（设计 / 需求里的禁止项、兼容要求、非功能约束）；③ 已知坑（**当前上下文已有的**坑、历史被否决的方案、用户刚提的教训）；④ 任务自身高危面（数据 / 权限 / 资金 / 不可逆操作 / 公开接口）。

> **不越边界**：提炼护栏**不额外检索知识库 / 记忆 / 专家资产**（与「边界」第 3 条一致）——只取当前上下文已有的与用户给的；**宁可少写一条，不为凑数去查**。

**数量 3-7 条；没提炼出来就整节省略**（宁缺毋滥，留空节就是假动作）——不足 3 条**不建该节**，零散约束写进相关工作项「备注」或清单对应组（**别塞进完成判据**：判据是终态、护栏是过程，混进去就不可判定）；超过 7 条说明任务该拆了。**豁免**：高危任务（数据 / 权限 / 资金 / 不可逆）只提炼出 1 条也保留该节。

**建档即输出**：向用户展示「目标 + 完成判据 + **注意事项** + 工作项列表 + 清单项及严重度 + 文件路径」，一句话确认即可开工；用户不回应则按当前理解继续，不阻塞（**高危任务**——多文件改动或涉及数据 / 权限 / 资金——建议请用户过一眼**护栏与清单**）。

### Step 2：执行中更新

**更新时机**（命中即更新，一次只花几行）：

- 完成 / 阻塞 / 取消一个工作项 → 改状态 + 补证据
- 方案改变、范围变化 → 追加「决策与偏差」一行
- 每轮对话结束前（尤其要中断时）→ 追加「进度日志」一行，写清"下次从哪继续"
- **开工 / 续做** → 先读一遍「注意事项」，本轮动作按它约束（几秒钟，不另做仪式）
- 标「已完成」时该工作项**触及护栏** → 证据列附 `守 #N → 已确认（怎么确认的）`
- 执行中**发现新的坑** → 追加护栏行（标 `[执行中发现]`）**并同步在 checklist E 组补一条**——只加进 plan 不补清单，验收必然漏检

> 时机本身以 `plan-track` 规则「二、进入后的节奏」为准（SSOT）；本节只细化**每类更新要写什么**。

**状态枚举**（只用这六个，不自创）：

| 状态 | 含义 | 允许流转到 |
|------|------|-----------|
| 待办 | 未开始 | 进行中 |
| 进行中 | 正在做 | 已改未验 / 阻塞 |
| 已改未验 | 改动完成但**未验证** | 已完成（补证据）/ 阻塞 |
| 已完成 | **有证据**证明达成 | - |
| 阻塞 | 缺前置或待用户决策 | 进行中 |
| 取消 | 明确不做（须写原因） | - |

**红线**：不得把「已改未验」直接写成「已完成」；不得把多个工作项一次性批量标完成——逐项验证、逐项标。**护栏不适用时不得删行**：在「决策与偏差」记一行说明，并在该护栏行备注标 `[已裁决不适用]`——删行等于把已知风险从台账里抹掉。更新计划是**几行文件的直接编辑**，不做任何额外查证仪式。

### Step 3：完成后自评审

**触发**：任务主体完成（所有工作项到达「已完成 / 取消」），或用户说"自检一下"。

**动作**：

1. 读 `checklist.md`，**逐条**（**含 E 组护栏与 F 组上游导入项**）核验——需要实跑的实跑（命令 / 测试 / lint），不靠读代码判断
2. 每条回填结论 + 证据（结论三档：✅ 通过 / ⚠️ 存疑 / ❌ 未通过）
3. **评审期只回填、不改题**：不得修改清单项文字或调低严重度；确需修改（如任务范围变更）必须在该行标注 `[评审期修改]` 并写明原因
4. **护栏单独过一遍**（E 组）：未遵守项先分清是"做法改了但没留痕"还是"真踩线"——前者回补 plan.md「决策与偏差」，后者按级别处置；**只写进 plan 而没进清单的护栏，此处补检**
5. 汇总：`通过 N / M`，列出 **P0 未通过项**
6. 处置：
   - **P0 未通过 > 0** → 修复后复查，**最多 3 轮**；3 轮仍不清零 → 停止自动修复，向用户呈报未决项
   - **P0 清零** → `plan.md` 与 `checklist.md` 状态分别置「已完成」「通过」

**与 auto-review 的分工**：`use_skill("auto-review")` 是**每次写文件后**的自动闭环（文件级）；本步是**整个任务做完**的检查（任务级）。两者叠加执行，互不替代。

### Step 4：收尾

**收尾顺序固定：状态收口 → `auto-review` → `acceptance-verify` → `implementation-report`**（前一步不通过不进下一步）。

1. **状态收口**：`plan.md` → 已完成 / 已放弃；`checklist.md` → 通过（附评审结论）
2. **跑一遍 `use_skill("auto-review")`**：对本次任务的**产出物**（代码 / 文档 / 配置）做交付前审查闭环（复杂场景会自动接力 `challenger`）——**先审查、后验收**；若审查要求修复，修完**回到 Step 3 复查**（自评审是闸门；`.plans/` 台账自身的更新不触发审查，见规则例外）
3. **需要交付验收时** → `use_skill("acceptance-verify")`，**把 plan.md 的护栏与 checklist E 组（护栏镜像）、F 组（上游导入项）结论一并作为验收输入**（自评审与 auto-review 都**不能替代**它；未安装或非交付类任务则提示用户自行验收，并**附上护栏清单请其过一眼**）
4. **实现类任务归档** → 交接 `use_skill("implementation-report")`（**验收通过后再归档**；未安装或非实现类则直接结束）
5. **有可复用经验** → 按 `use_skill("loop-discovery")` 路由决定是否沉淀（未安装则按用户意愿处理）
6. **保留 `.plans/` 目录**：不删除，作为执行历史与同类任务参照

## 模板

### plan.md

````markdown
---
task: {一句话任务名}
status: 进行中        # 进行中 / 已阻塞 / 已完成 / 已放弃
created: {YYYY-MM-DD}
updated: {YYYY-MM-DD}
related: {REQ-XXX / 需求名 / 设计文档路径 / -}
---

# 执行计划：{任务名}

## 目标
做完之后会怎样（可观测的最终状态，一句话）

## 完成判据
- [ ] {可判定判据，如"命令 X 输出 Y" / "文件 Z 存在且含 W"}

## 注意事项（执行护栏）
| # | 注意事项 | 来源 | 违反后果 |
|---|----------|------|----------|
| 1 | {动作化、可判定：不要做什么 / 必须做什么} | {用户要求 / 上游文档 / 已知坑 / 高危面} | {P0：错结果 / 数据损坏 / 不可逆；P1：可维护性 / 体验} |

> 3-7 条，**没提炼出来就删掉整个小节**；每条一对一生成清单 E 组。工作项证据引用：`守 #1 → 已确认（怎么确认的）`

## 工作项
| # | 工作项 | 状态 | 证据 | 备注 |
|---|--------|------|------|------|
| 1 | {} | 待办 | - | |

> 证据写法：`命令 → 观察到的输出` / `文件:行号` / `测试名 → 结果`

## 决策与偏差
| # | 事项 | 决策 / 偏差 | 原因 |
|---|------|------------|------|

## 进度日志
- {YYYY-MM-DD HH:mm} {}
````

### checklist.md

````markdown
---
task: {同 plan.md}
status: 未评审        # 未评审 / 评审中 / 通过 / 未通过
updated: {YYYY-MM-DD}
---

# 自评审清单：{任务名}

> 用法：任务主体完成后**逐条**核验并回填证据；无证据视为未通过。**严重度在建档时定死，评审期不得修改**（改题即失去闸门意义）。
> 结论三档：✅ 通过 / ⚠️ 存疑 / ❌ 未通过。**排查手段不足时只能标 ⚠️ 存疑，不得标 ✅**。
> **E 组由 plan.md「注意事项」一对一生成**（严重度取「违反后果」列）；执行中新发现的护栏必须同时补进本组，否则验收漏检。

## A 完成度
| # | 检查项 | 严重度 | 结论 | 证据 |
|---|--------|--------|------|------|
| A1 | 所有工作项为「已完成」或有明确「取消」理由 | P0 | | |
| A2 | 无「已改未验」遗留 | P0 | | |

## B 正确性
| B1 | 改动已实跑验证（命令 / 测试 / lint），非仅读代码判断 | P0 | | |
| B2 | 关键路径有可复现的验证记录 | P0 | | |
| B3 | 异常 / 失败分支有处理或有明确说明 | P1 | | |

## C 影响面
| C1 | 受影响的调用方 / 消费端已排查 | P0 | | |
| C2 | 遗留 TODO / FIXME 已登记 | P1 | | |
| C3 | 与设计 / 计划的偏差已记入 plan.md「决策与偏差」 | P1 | | |

## D 交付
| D1 | 文档 / 注释与实际实现一致 | P1 | | |
| D2 | 未引入敏感信息（凭据 / 内网地址 / 个人数据） | P0 | | |
| D3 | 收尾动作明确（提交 / 报告 / 归档 / 交接） | P1 | | |

## E 护栏遵守（一一对应 plan.md「注意事项」）
| E1 | {由注意事项 #1 转成可判定问法} | {P0/P1} | | |

## F 上游清单导入（可选；来源为上游报告里的待办项，如 `code-review` 报告「检查覆盖表」的 ❌/⚠️ 项）
| F1 | {由上游报告项转成的可判定问法} | {P0/P1} | | |

## 评审结论
- 通过：{N} / {M}
- P0 未通过（阻断）：{列出，或"无"}
- 处置：{修复后复查 / 交接 / 报用户裁定}
````

**清单定制**：A/B/C/D 是默认骨架，**E 组由 plan.md「注意事项」一对一生成**（无护栏则整组省略），按任务类型再增补（增补项见 [reference.md](reference.md)）；**F 组仅在上游报告导入了待办项时生成**（无上游则整组省略）；**删掉不适用项比留着空项好**——空勾就是假通过。

> **E 组与 F 组的区别**：E 组来自本任务的**过程约束**（护栏：别踩什么线），F 组来自**上游判断结果**（该修什么）。两组都只转写、不复制上游原文，并保留原锚点（上游报告编号 / 需求 AC-N）。

## 常见反模式

- ❌ 为小任务建档 → 形式主义，由 `plan-track` 规则的场景识别（Step 0）挡住
- ❌ 无证据标「已完成」 → 台账变幻觉，由 Step 2 红线挡住
- ❌ 计划写完不再更新 → 活文档退化为一次性文档；Step 2 的更新时机是强制的
- ❌ 平行台账（本计划 + 骨架状态 + 另起的 TODO 文件）→ 违反核心原则 3
- ❌ 清单写不可判定项（"代码优雅""逻辑清晰"）→ 无法判定 = 无法放行
- ❌ 注意事项写成软提示（"注意代码质量""保持一致"）→ 同上，护栏必须动作化 + 带后果
- ❌ 护栏只写进 plan.md、没进 checklist E 组 → 验收时压根不会被检查（Step 3 第 4 步补检是兜底，不是默认路径）
- ❌ 执行中悄悄删掉不适用的护栏 → 已知风险从台账消失，应走「决策与偏差」留痕
- ❌ 用自评审替代交付验收 → 自评只是内部闸门，验收归 acceptance-verify / 用户
- ❌ 任务完成后删档 → 丢失执行历史，同类任务无法参照

## 更多资源

- 注意事项（护栏）字段详解、按任务类型的清单增补项、跨会话续做流程、完整示例，参见 [reference.md](reference.md)