用途
Task Planning 用于把 Paperclip 的 issue 或请求转化为结构化实施计划，使 Paperclip 执行器能够真正运行：明确的子 issue、真实的阻塞关系、指定的负责人以及清晰的验收标准。它避免产出“读起来不错但无法拆分为工作”的计划。
何时使用
- 某个 issue 要求你进行“规划”“界定范围”“拆分”“设计上线方案”“提出工作内容”或类似操作。
- 用户希望在批准实施前先看到书面计划。
- 管理者需要委派非平凡工作，而工作的形态尚不明确。
- 你接手了一个大到无法在单个心跳周期内交付的 issue，需要拆分它。
何时不使用
- 该 issue 是可以在同一心跳周期内交付的单个小改动。直接交付即可。
- 该 issue 属于取证性质（“为什么坏了”）。先使用诊断技能；只有在根因明确后才进行规划。
- 已存在当前计划文档且改动很小。更新该文档，不要重新开始。
输出
- 更新后的 issue 文档，包含关键计划（markdown）。
- 在 issue 上发布一条简短评论，链接到计划文档并说明下一步行动。
- 如果计划需要批准，则创建一个 issue 线程交互，类型为 request_confirmation，并绑定到最新计划修订版。
计划被接受前，不要创建实施子任务。
计划结构
必需章节，按顺序排列：
- 目标 — 一段话。说明这项工作落地后，用户、操作者或系统会发生什么变化。
- 已审阅上下文 — 列出你阅读过的文档、文件和先前 issue。便于审阅者发现缺失的输入。
- 约束与非目标 — 必须成立的条件（兼容性、安全性、性能）以及本计划刻意不做的事情。
- 方案 — 选定的路径，附简短理由。如果考虑过替代方案，说明它们以及为何被拒绝。
- 工作分解 — 有序的子 issue 列表。每个子任务包含：
- 祈使句形式的标题。
- 负责人专业方向（Engineer、QA、Designer、Security、DevRel、Manager 等）。
- 范围与交付物。
- 验收标准。
- 通过阶段字母或子任务标题表达的阻塞/被阻塞关系。
- 验收 — 父 issue 的验收标准。用户如何知道整件事已完成。
- 风险与缓解 — 简短列表。如果没有可跳过。
- 延期项 — 有意推迟到后续 issue 的内容及原因。
拆分经验法则
- 一个子 issue，一个专业方向。如果两个专业方向必须在同一 issue 内协调，就拆分它。
- 一个子 issue，一个验收结论。如果审阅者会说“这完成了一半”，就拆分它。
- 子任务必须仅凭标题和描述就能被负责人领取。审阅者不应为了理解子任务而重读父计划。
- 按真实阻塞链排序子任务，而不是按作者偏好。并行子任务应明确写明“阻塞：无”。
- 避免没有验收标准的打磨或清理类子 issue——它们永远不会关闭。
提交计划
使用 Paperclip API 写入计划文档，然后评论：
PUT /api/issues/{issueId}/documents/plan，请求体为 markdown 内容。如果计划已存在，需包含最新的 baseRevisionId。POST /api/issues/{issueId}/comments，发布简短摘要并链接计划：/<prefix>/issues/<issue-id>#document-plan。- 如果需要批准：
POST /api/issues/{issueId}/interactions，设置kind: request_confirmation、targetRevisionId为新计划修订版、continuationPolicy: wake_assignee、idempotencyKey: "confirmation:{issueId}:plan:{revisionId}"。
创建确认后将 issue 设为 in_review。保持分配状态，以便验收时唤醒规划者。
计划被接受后，参见配套技能，将已接受的计划转换为 Paperclip 可执行任务。该技能涵盖的关键要求：生成紧凑的任务矩阵（任务、负责人、初始状态、阻塞项）；将每个硬依赖编码为 blockedByIssueIds——仅靠父子嵌套不会阻塞执行；在关闭源规划 issue 前验证创建的 issue 图。
反模式
- 把计划伪装成描述编辑。应使用计划文档。
- “阶段 A–Z”但阶段内部没有工作分解。
- 子任务描述写“见父任务”——它们在委派时会失败。
- 验收写成“代码审查通过”。审阅者需要行为标准，而不是流程标准。
- 把阻塞链埋在散文里。应使用明确的 blocked-by 行。