| name | writing-plans |
| description | 在已有设计文档或清晰需求、但还没开始实现时，把目标写成可执行的分步实施计划。适用于跨文件改动、非平凡功能、重构，以及任何需要明确测试或验证命令的任务。只要用户要把已定需求、现成 spec、明确目标，或 /grill-with-docs / /grilling 后达成的共识，拆成 step-by-step plan，就优先使用这个 skill；如果设计还没定，不要硬写计划，退回 brainstorming 或 grill-with-docs 把设计做扎实。 |
| argument-hint | 提供已批准的设计文档、需求摘要、目标功能或期望路径；可留空 |
Writing Plans Skill
这个 skill 用于把已批准的设计或足够清晰的需求，转换成普通编码 agent 或人工执行者可直接消费的实施计划。
这是一个 planning skill，不是 execution skill。
在这个 skill 中，先写计划，再决定是否开始实现。
何时使用
在以下场景优先使用这个 skill：
- 已经有批准过的设计文档，需要拆成具体实施步骤
- 需求已经足够清晰，但改动不适合直接开写
- 工作会分成多个任务、多个文件或多个验证点
- 需要在编码前把测试、验证命令、任务边界写清楚
- 需要把实现工作交接给后续执行者
不要路由到 writing-plans
以下请求默认不要使用这个 skill：
- 还处在需求澄清和方案比较阶段
- 直接实现、改代码、写补丁、跑测试
- 代码审查、交接总结、状态同步
- 简单事实问答或代码解释
如果还没有批准过的设计或达成共识，走 PHASE 0 的"方案未定"三选 fork（brainstorming / grill-with-docs / 补需求）。
红灯与反例
命中下列已知翻车点时按"信号 → 一线动作"先处理，再跳到"详见"里的处理器。本表是诊断索引——每条只写一线动作并指向详细规则归属，不在此重复正文：
| 信号 | 一线动作 | 详见 |
|---|
设计未批准 / 方案未定就硬写计划（unapproved-design-stop） | 🛑 STOP，走三选 fork（brainstorming / grill-with-docs / 补需求） | PHASE 0（方案未定分支） |
编造文件、命令或测试框架（missing-design-path-stop） | 🛑 STOP，说明缺口，不猜路径、不猜命令 | PHASE 0（路径分支）、PHASE 1 |
一个请求横跨多个独立子系统（multi-subsystem-split） | 🛑 STOP，先拆成多份计划，每份独立可验证 | PHASE 0（多子系统分支） |
跳过文件结构直接列任务（skip-file-structure-first） | 回 PHASE 2 先规划文件结构与职责 | PHASE 2 |
其余（不要占位符 / 不要省略接口契约 / 交接终点是 handoff 等）已在硬约束与各 PHASE 里正面规定，此处不重复。
硬约束
- 输出顺序：先规划文件结构和职责，再拆任务；先写完整计划和 inline 自检，再交给用户审阅；未获批准前不进入实现。
- 验证要求：每个任务都必须有明确验证；没有验证的任务不算完成；checkpoint commit 只在自然边界使用，不要求每个微步骤都提交。
- 路径与契约：使用精确文件路径；定位优先用“路径 + 符号/章节锚点 + 可选当前行段”，不要把行号当成唯一契约。
- 全局约束：逐字保留设计文档里的版本下限、依赖限制、平台要求、命名规则和文案规则；没有全局约束时明确写“无额外全局约束”。
- 命令环境：验证命令匹配当前 shell / 平台与仓库惯例；依赖特定 shell 或工具时显式写明（如 Windows 上用 PowerShell 等价命令，不写 bash-only）。
- 禁止占位符：不要写
TODO、TBD、later、add validation 这类空话。
PHASE 0: 验证输入
开始前先确认：
- 输入是以下任一：已批准的设计文档；
/grill-with-docs 或 /grilling 后达成的共识（盘上有 ADR / CONTEXT 就读作设计来源，没有就把对话本身当足够清晰的需求）；或至少足够清晰、能直接拆任务的需求
- 当前工作是否跨多个独立子系统
- 是否已经知道关键路径、受影响文件范围和主要验证方式
- 输入里是否还存在明显的方案未定、关键约束缺失或逻辑矛盾
如果设计仍然覆盖多个独立子系统：
- 🛑 STOP：先拆成多份计划，不要把多个子系统塞进同一份计划
- 每份计划只覆盖一个可以独立完成和验证的子项目
- 只有拆分边界明确后，才继续进入 Phase 1
如果输入仍然存在明显的方案未定、关键约束缺失或逻辑矛盾：
- 🛑 STOP：明确说明当前输入还不适合直接写计划
- 明确指出缺的是哪一类信息：批准过的设计、达成共识、关键路径、受影响文件范围，还是验证方式
- 选一条设计轨道补设计——
brainstorming（还在比较方案 / 需要多选澄清 / 目标边界没钉住时）、grill-with-docs（已有想法或草稿 / 对抗式压力测试 / 顺带沉淀 ADR glossary 时）、或直接补一份更清晰的需求（只是缺几条约束 / 不必走完整设计流程时）
如果用户给出的设计文档路径表达不确定、文件不存在或不可读：
- 🛑 STOP：说明缺口，不猜路径、不猜命令，不生成完整计划（路径可读但范围/验证方式仍不明的情况，见下方"不知道关键路径"分支）
如果还不知道关键路径、受影响文件范围或主要验证方式：
- 继续读取最小必要上下文，只补到能回答这三个问题为止
- 如果补完最小上下文后仍然说不清，按上面的 🛑 STOP 规则停下并说明缺口
PHASE 1: 读取最小必要上下文
在写计划前，先读取最小必要上下文：
- 设计文档或需求摘要
- 相关文件、测试、命名模式、目录约定
- 已存在的验证命令、测试框架、脚手架模式
目标不是把全仓库看完，而是回答：
- 这次改动应该落到哪些文件
- 哪些命名和边界必须沿用
- 最便宜的验证方式是什么
如果这三个问题已经答清，就停止继续搜索，不要把 Phase 1 扩成仓库漫游。
PHASE 2: 先规划文件结构
在定义任务前，先列出文件结构和职责：
- 会创建哪些文件
- 会修改哪些文件
- 每个文件承担什么职责
- 哪些文件应该一起变化，哪些边界必须保持稳定
- 从设计文档继承哪些全局约束
- 哪些任务之间存在接口依赖，接口名称是什么
规则：
- 优先跟随现有仓库模式
- 文件按职责拆分，不按想象中的“技术层”硬切
- 如果某个现有文件已经过大，可以在计划里纳入一次与当前需求直接相关的拆分
- 不做和当前目标无关的重构
如果计划会被分任务交给不同执行者，每个任务都要能单独读懂。前序任务产出的函数、类型、配置键、路径或文档章节，必须在后续任务的接口契约里重复写明，不要要求执行者“参考前文”。
PHASE 3: 拆成可执行的小任务
任务要足够小，通常以 2-5 分钟的单步为粒度。
每个任务都只覆盖一个可独立验证的工作块。出现以下信号时，必须继续拆分：
- 一个任务标题里同时出现两个以上主要动作，例如“清理并更新”“迁移与重写”“同步并验证”
- 一个任务同时承担两个以上主要职责，例如既改入口文档，又改规则路由
- 一个任务跨越多个不共享同一验证命令的文件组
- 执行者做完这个任务后，无法用一次明确验证判断它是否完成
任务也不能拆得过碎：setup、配置、脚手架、文档更新通常应折进真正需要它们的交付任务。这叫 reviewer gate——只有当 reviewer 可以单独拒绝某个任务、同时接受相邻任务时，独立任务边界才成立。
对代码变更，优先使用验证驱动循环：
- 写失败测试或失败检查
- 运行并确认当前失败
- 写最小实现
- 运行并确认通过
- 可选：做一次 checkpoint commit
如果某类工作不适合严格 TDD：
- 仍然要定义“改动前可观察到的失败或缺失”
- 仍然要定义“改动后可观察到的通过条件”
任务必须满足：
- 独立可理解
- 涉及文件明确
- 接口契约明确；如果依赖前后任务，写清 Consumes / Produces
- 命令明确
- 命令与当前执行环境一致
- 预期结果明确
- 每个 Step 都写真实动作；不要只列动作标题，不写运行方式和通过信号
如需固定骨架，先读取 references/task-skeleton.md。
PHASE 4: 写实施计划文档
路径选择顺序：
- 用户显式指定路径
- 仓库已有计划文档约定
- 默认写到
docs/plans/<YYYY-MM-DD>-<feature>-implementation-plan.md
如需固定骨架，先读取 references/plan-template.md。
实施计划至少覆盖：
- 目标
- 架构快照
- 全局约束；从设计文档逐字继承版本、依赖、平台、命名和文案规则
- 文件结构与职责
- 任务清单
- 任务间接口契约；涉及前后依赖时写清 Consumes / Produces
- 每个任务的验证命令与预期结果
- 如验证依赖特定 shell 或工具，写明环境前提
- 执行纪律
- 最终验证
计划正文格式要求：
- 文档第一行就是标题，不写前导说明
- 架构快照控制在必要范围，只解释本次方案，不复述仓库背景
- 任务清单优先直接写正式计划，不写“计划预览”“任务示例”“后续操作”这类过渡段落
PHASE 5: Inline 自检
写完计划后，读取 references/plan-self-review.md 并完成单轮 inline 自检。
优先修复会让执行者卡住或把事情做错的问题：
- 设计要求没被覆盖
- 设计里的全局约束没有进入计划
- 任务仍有占位符
- 后文命名和前文定义不一致
- 后续任务依赖的接口、类型、文件或命令没有在前序任务定义
- 命令不存在或验证方式模糊
- 某个任务大到不可执行
不要为了措辞做多轮循环。修完就继续。
PHASE 6: 🔴 CHECKPOINT · 用户审阅与执行交接
计划通过自检后，立即停下，让用户先审阅。未获批准，不进入实现。
交接时使用如下表述：
实施计划已写好并保存到 <path>。请先确认这份计划；如果没问题，下一步可以按计划由普通编码 agent 或人工继续执行。
如果用户要求修改：
- 修改计划
- 重新跑同一轮 inline 自检
- 再次请求审阅
如果用户批准：
- 明确说明这份计划的默认执行方是普通编码 agent 或人工执行者
- 不要调用不存在的下游 skill
- 不要在本 skill 中直接切入编码
执行纪律
把下面的纪律写进计划正文：
- 开始实现前，先批判性复查整份计划；如果发现缺项、矛盾、命名不一致或验证命令无效，先修计划
- 按任务顺序执行，不要无声跳步、合并步或改变任务目标
- 每完成一个任务，都运行该任务定义的验证
- 遇到阻塞、重复失败或计划与仓库现实不符，立即停下来说明，不要猜
- 如果当前就在
main 或 master，且用户没有明确同意，开始实现前先确认
- 全部任务完成后，运行最终验证并输出修改摘要
关键原则
File structure first · Reviewer gate · Consumes / Produces · Bite-sized · Follow the repo · Stop when blocked · Runtime-neutral（各词已在对应 PHASE 与硬约束里定义）
立即执行
先验证输入是否足够，然后读取最小必要上下文，规划文件结构，拆任务，写计划并完成 inline 自检。
