plan

实施规划技能

概述

撰写唯一一份统一的 docs/specs/ 文档中的 ## Decomposition 部分，列出细粒度、可并行执行的任务，并追溯到同一文档 ## Design & Rationale 部分中的 DR-N 需求。不存在第二个文件：追溯关系在同一份文档内闭合。通过明确的内部追溯确保完整覆盖。文档结构由 references/spec-template.md 规定——请据此撰写。

完整示例请参见 references/worked-example.md。

触发条件

在以下情况下启用此技能：

• 用户运行 plan 命令
• 用户希望将规格拆分为任务
• 统一的 docs/specs/ 文档中的 Design & Rationale 部分需要拆解
• 用户说“规划实施”或类似的话
• 在撰写完 Design & Rationale 部分后，由 ideate 自动接续
• 直接运行（之前未运行 ideate）：在浅层／标准深度下，一次性撰写完整的统一规格——轻量／标准的 Design & Rationale 部分加上 Decomposition
• 由 plan-review 搭配 --revise 标志自动接续（发现缺漏）

修订模式（--revise 标志）

使用 --revise 调用时，plan-review 已发现缺漏。从状态中读取 .planReview.gaps，重新阅读设计，添加任务以弥补每项缺漏，更新计划文件，然后通过 exarchos:exarchos_workflow 执行 action: "update" 清除缺漏。

修订循环保护

每个计划最多修订 3 次。

连续修订 3 次仍未通过后：

1. 将 planReview.revisionsExhausted 设为 true
2. 输出：“Plan revision failed after 3 attempts. Design may be incomplete.”
3. 升级处理：建议使用 ideate --redesign 重新审视设计

强制要求： 在接受任何关于跳过测试、规划或 TDD 步骤的合理化说辞之前，请查阅 references/rationalization-refutation.md。其中列出了常见借口、反驳理由及正确做法。

验证阶梯

验证深度与影响范围相匹配。更深的阶梯会增加测试、充分性杀探针和集成覆盖——依据结果、测试后来判断，而非遵循普遍适用的先写失败测试定律。每项任务都采用能够覆盖其风险的最低成本验证方式：

风险级别	增加的内容	原因
low	静态分析（类型检查 + lint）即可满足要求	仅涉及文档/配置/重命名的修改，影响范围几乎为零；测试仪式纯属额外开销。
medium	范围限定的测试 + check_test_adequacy 杀探针	杀探针以更低成本重现了测试先行的唯一实际保证——测试确实可以失败；通过测试后判断，而非要求每次提交都先写一个失败测试。
high	在 medium 的基础上增加集成测试套件（并在边界处进行变异充分性检查）	Schema/类型/API/共享契约会横跨整个代码库；在这些情况下，经过充分性判断的覆盖，加上跨边界与真实协作者的集成，值得投入这项成本。

规划器会为每项任务标记其 riskTier（和 boundaryTouching）；若规划器未覆盖该标记，分类器会根据影响范围推导。派发给实现者的提示词和门禁顺序都会依据该标记进行调整——因此，验证工作量由数据驱动，而非一刀切的规则。

对于高风险级别任务，采用基于结果的规范（按自然顺序编写行为及其测试——测试后编写也可以）：

1. 使用范围限定的测试覆盖新增/变更行为，并明确其契约
2. 让 check_test_adequacy 杀探针证明测试确实可以失败（它会还原源代码，并断言至少有一个测试变为失败）
3. 增加跨边界、与真实协作者的集成覆盖

实现后验证高风险级别任务的测试充分性——使用 keeper 门禁（测试先行顺序门禁 check_tdd_compliance 已弃用）。传入 repoRoot: "auto" 和任务的工作树。探针会还原并随后恢复其运行所在树的源代码。若缺少这两个字段，该树会是服务所在目录，通常就是你自己的检出目录。还需传入任务分叉自的分支 baseBranch。若缺少该字段，门禁会因 base-missing 而阻止操作：

exarchos_orchestrate({
  action: "check_test_adequacy",
  featureId: "<featureId>",
  taskId: "<taskId>",
  branch: "feature/<name>",
  baseBranch: "<branch the task forked from>",
  repoRoot: "auto",
  worktreePath: "<worktreePath>",
  riskTier: "high"
})

• passed: true — 还原任务的源代码后，至少有一个新增/变更测试失败：这些测试并非空洞测试
• passed: false — 仍有测试在还原后的源代码上通过；请加强测试

规划流程

步骤 1：分析「设计与理由」部分

仔细阅读统一规范中的 ## Design & Rationale 部分（如果运行了 ideate，此部分已编写；否则现在按薄/标准深度编写，参见 references/spec-template.md）。从中提取：

• 问题陈述 — 背景（不涉及任务，但有助于确定范围）
• 选定方案 — 要实现的架构决策
• 需求（DR-N） — 每项任务都必须追溯到的来源锚点
• 技术设计 — 核心实现要求
• 集成点 — 集成和胶水代码任务
• 未决问题 — 需要解决或明确推迟的决策

步骤 1.5：规范追溯（必需）

在统一文档内创建可追溯矩阵，将 DR-N 需求映射到计划任务。 参阅 references/spec-tracing-guide.md，了解方法和模板。

使用可追溯性生成器预填矩阵——将统一的 docs/specs/ 产物同时作为 designFile 和 planFile 传入（它会从该文件的 ## Design & Rationale 区域解析 DR-N，从 ## Decomposition 区域解析任务）：

exarchos_orchestrate({
  action: "generate_traceability",
  designFile: "docs/specs/<date>-<feature>.md",
  planFile: "docs/specs/<date>-<feature>.md",
  outputFile: "docs/specs/<date>-<feature>-traceability.md"
})

• passed: true — 已生成矩阵；请检查并填写「关键需求」列
• passed: false — 解析错误；规范可能缺少预期的 ##/### 标题

第 2 步：拆分为任务

每个任务都遵循 references/task-template.md 中的 TDD 格式。

Implements: DR-N 和任务 ID 是规范以及 task.completed 事件的字段，溯源链会从中读取这些信息。不得将它们带入代码注释；注释应以文字说明约束，不得提及规划序号；参见 references/task-template.md 中的 序号是工件元数据，而非代码。将每个任务的验证说明写成对所需行为的描述，这样实现者照用这些措辞时，写下的是约束，而不是序号。

粒度指南：

• 每个任务：专注工作 2-5 分钟
• 一个测试 = 一种行为
• 优先选择多个小任务，而非少数几个大任务

使用 references/testing-strategy-guide.md 为每个任务指定 testingStrategy，以控制 Agent 应采用哪些验证技术。根据任务描述和文件路径与类别表的匹配情况，自动确定 propertyTests 和 benchmarks 标志——不要把这些留给实现者决定。

任务排序：

1. 先处理基础内容（类型、接口、数据结构）
2. 再处理核心行为
3. 然后处理边缘情况和错误处理
4. 最后处理集成和衔接代码

第 3 步：确定并行化方案

分析依赖关系，找出必须按顺序执行的任务链，以及可以在工作树中同时执行的安全并行任务组。

第 4 步：编写分解部分

使用 references/spec-template.md，将 ## Decomposition 部分写入统一规范 docs/specs/YYYY-MM-DD-<feature>.md。其中的 ## Decomposition 应包含任务拆分，并在同一份文档内与上文 ## Design & Rationale 中的 DR-N 来源建立可追溯关系。

旧版双文件拆分方式（references/plan-document-template.md → docs/plans/）仅保留给仍在旧流程中进行的工作；新功能应只编写一份 docs/specs/ 工件。

第 5 步：计划验证

运行确定性验证脚本，而不是手动检查清单。每个脚本都将统一的 docs/specs/ 工件同时作为 designPath 和 planPath——处理程序会从其设计区域解析 DR-N，并从其分解区域解析任务。

5a. 覆盖率 — 验证每项设计与理由要求都对应到一项任务（原先合并的设计完整性验收标准检查现已纳入此处）：

exarchos_orchestrate({
  action: "check_plan_coverage",
  featureId: "<id>",
  designPath: "docs/specs/<date>-<feature>.md",
  planPath: "docs/specs/<date>-<feature>.md"
})

• passed: true — 所有要求均已覆盖；继续执行 5a-ii
• passed: false — 发现缺漏；为未覆盖的要求添加任务，或说明理由后延期
• error — 用法错误或规范为空；检查参数

5a-ii. 来源链验证 — 验证每项 DR-N 要求都通过 Implements: 字段对应到一项任务：

exarchos_orchestrate({
  action: "check_provenance_chain",
  featureId: "<id>",
  designPath: "docs/specs/<date>-<feature>.md",
  planPath: "docs/specs/<date>-<feature>.md"
})

• passed: true — 所有 DR-N 要求均已追溯；继续执行 5b
• passed: false — **阻止：**发现缺漏或孤立引用。为每项未覆盖的要求，在任务中添加 **Implements:** DR-N 后再继续。每项 DR-N 要求都必须追溯到至少一项任务。
• error — 设计中没有 DR-N 标识符（退出码 2）；如果设计未使用 DR-N 标识符，则跳过此检查（豁免）

5a-iii. D5：任务分解质量（建议性） — 验证每项任务是否具有清晰的描述、文件目标和测试预期；依赖关系图是否为有效的 DAG；可并行任务是否修改了相同文件：

exarchos_orchestrate({
  action: "check_task_decomposition",
  featureId: "<id>",
  planPath: "docs/specs/<date>-<feature>.md"
})

• passed: true — 所有任务的分解均符合要求；继续执行 5b
• passed: false — 将发现记录为 ConvergenceView 的 D5 门禁事件。向用户展示发现以供了解，但不要阻止计划获批。
• error — 输入错误（缺少文件或没有任务标题）；检查参数

**建议性：**此门禁用于验证任务结构质量，但不会阻止计划获批。发现将被记录下来，用于跟踪收敛情况。

5b. 规范覆盖率检查 — 将计划中的测试路径作为声明进行验证：

exarchos_orchestrate({
  action: "spec_coverage_check",
  featureId: "<feature-id>",
  planFile: "docs/specs/<date>-<feature>.md",
  repoRoot: ".",
  coveragePhase: "plan"
})

此处传入 coveragePhase: "plan"。在规划阶段，声明的测试文件尚不存在，因此此项检查会验证路径是否为格式正确的测试路径声明，而不会要求文件已存在于磁盘上。省略此参数会回退到 post-implementation，该阶段要求每个已声明文件都存在且其测试已运行——任何计划都无法达到这一标准。

• passed: true — 每条声明的测试路径都是有效的前置声明；计划验证完成
• passed: false — 某条声明的路径不是格式正确的测试路径；修正计划中的路径

有关底层方法，请参阅 references/spec-tracing-guide.md。

反模式

不要	应该
发布没有测试的中/高风险等级行为	使用经充分性评估的测试覆盖（先实现后测试也可以）
要求每项任务都遵循红-绿-重构	根据任务的 riskTier 调整验证力度；RGR 是高风险等级的可选做法
创建大型任务	拆分为 2-5 分钟的小块
跳过依赖分析	找出可并行的工作
使用含糊的测试描述	具体描述：方法_场景_结果
假定测试可能失败	让 check_test_adequacy 证明测试确实能失败（还原源代码、重新运行并预期出现失败）
添加“锦上添花”的代码	只添加行为所需的内容

驳斥合理化借口

这套分级机制已考虑了确实低风险的工作——因此，这些借口适用于中/高风险等级任务，在这些任务中，它们是合理化借口，而非合理的分级选择：

借口	事实
“这太简单了，不值得写测试”（针对中/高风险等级任务）	如果它涉及影响范围大的表面，其风险等级就不低。按分级机制指定的等级测试它。
“我之后再补测试”	你不会补。或者测试会很薄弱——而 check_test_adequacy 会发现无法失败的测试。
“测试会拖慢我”	调试未经测试的中/高风险等级变更更慢。
“设计很明显”	现在对你来说很明显。3 个月后就未必了。

状态管理

保存规范时，记录制品，并根据 workflowType 转换阶段：feature → plan-review，refactor → overhaul-plan-review。将 artifacts.plan 设为统一的 docs/specs/ 路径——这是 planArtifactExists 守卫读取的键，它指向唯一的统一文档（与 ideate 记录为 artifacts.spec 的路径相同）。制品和阶段需要分别调用：update 仅用于非阶段变更；阶段变更则通过受 HSM 守卫保护的 transition 操作完成：

action: "update", featureId: "<id>", updates: {
  "artifacts": { "plan": "docs/specs/<date>-<feature>.md" },
  "tasks": [{ "id": "001", "title": "...", "status": "pending", "branch": "...", "blockedBy": [] }, ...]
}
action: "transition", featureId: "<id>", target: "<plan-review-phase>"

阶段转换与守卫

完整的转换表请参阅 @skills/checkpoint/references/phase-transitions.md。

快速参考： plan → plan-review 转换需要 plan-artifact-exists 守卫——在调用 transition 之前，将 artifacts.plan 设为统一的 docs/specs/ 路径。

Schema 发现

使用 exarchos_workflow({ action: "describe", actions: ["update", "init"] }) 获取 参数 schema；使用 exarchos_workflow({ action: "describe", playbook: "feature" }) （或 "debug"、"refactor"）获取阶段转换、守卫和 playbook 指引。 使用 exarchos_orchestrate({ action: "describe", actions: ["check_plan_coverage", "check_provenance_chain"] }) 获取 orchestrate 操作的 schema。

完成标准

• 已阅读并理解设计文档
• 已创建规范可追溯性表（exarchos_orchestrate({ action: "generate_traceability" })）
• 已声明范围（完整范围，或附带理由的部分范围）
• 任务已拆分至 2-5 分钟的粒度
• 每项任务都标注了 riskTier（及 boundaryTouching）；中/高风险等级任务包含经过充分性评估的测试（先测试）；高风险等级任务还需包含集成测试套件
• 已梳理依赖关系
• 已识别并行组
• 计划验证通过——exarchos_orchestrate({ action: "check_plan_coverage" }) 返回 passed: true
• 已检查溯源链——exarchos_orchestrate({ action: "check_provenance_chain" }) 通过（阻塞项；继续前必须解决所有缺口）
• 已检查任务拆分——已运行 exarchos_orchestrate({ action: "check_task_decomposition" })（仅供参考；会展示检查结果，但不阻塞）
• 规范覆盖检查通过——exarchos_orchestrate({ action: "spec_coverage_check", featureId: "<feature-id>" }) 返回 passed: true
• 已达到覆盖率阈值——exarchos_orchestrate({ action: "check_coverage_thresholds", featureId: "<feature-id>" }) 返回 passed: true：

exarchos_orchestrate({
  action: "check_coverage_thresholds",
  featureId: "<feature-id>",
  coverageFile: "coverage/coverage-summary.json",
  lineThreshold: 80,
  branchThreshold: 70,
  functionThreshold: 100
})

• 已将统一规范保存到 docs/specs/（在同一文档中包含设计与理由，以及任务拆分）
• 状态文件已更新，包含 artifacts.plan = 统一规范路径及任务

转换

拆分完成后，自动继续到 plan-review。转换到相应的审查阶段（feature：plan-review；refactor：overhaul-plan-review）。Plan-review 不再是对计划与设计进行差异对比的内联审查（现在只有一个制品），而是针对统一制品进行分派式、独立上下文、对抗性只读审查（DR-10）：为一名干净的审查者仅提供 {制品 + 规范}（绝不提供本次编写对话记录），并根据冻结的 designDepth 调整其对抗性审查深度。通过 exarchos_orchestrate({ action: "prepare_review", scope: "plan", artifact: "docs/specs/<...>", designDepth: "<frozen>" }) 配置审查者。

• 审查未通过（存在缺口）：设置 .planReview.gapsFound = true（修订守卫会读取此字段），并在 .planReview.gaps 中记录发现的问题，然后自动返回 plan --revise 循环
• 审查通过：提交给用户审批（唯一的人类检查点）
• 审批通过后：设置 .planReview.approved = true，调用 delegate

必需： 对统一制品运行 exarchos_orchestrate({ action: "check_plan_coverage" })。如果 passed: false → 自动调用 plan --revise。如果 passed: true → 转换到 plan-review 阶段，并且只有在 plan-review 获得批准后才调用 delegate。

Exarchos 集成

阶段转换会通过 exarchos_workflow 的 transition 自动发出 workflow.transition 事件。无需手动追加 exarchos_event。

故障排除

问题	原因	解决方法
check_plan_coverage 返回 passed: false	设计章节未映射到任务	为未覆盖的章节添加任务，或添加明确的延期理由
spec_coverage_check passed: false	缺少计划中的测试文件，或测试文件未通过	创建缺失的测试桩，并确认计划中的文件路径与实际路径一致
generate_traceability passed: false	设计文档缺少预期的 ##/### 标题	确认设计文档使用标准 Markdown 标题
修订循环（3 次或更多）	设计与计划之间存在持续差距	设置 planReview.revisionsExhausted = true，建议使用 ideate --redesign

性能说明

• 完成每个步骤后再继续下一步——质量优先于速度
• 即使变更看似微不足道，也不要跳过验证检查
• 将每个设计章节都追溯到至少一个任务。不要让任何章节在缺乏明确理由的情况下未被覆盖。