Research + Plan

任务：$ARGUMENTS

两段式。Research 段只读不写代码，Plan 段只写文档。全程不改任何源文件。

第 0 步 先劝退（最先做，不满足就直接停）

判据：如果这个改动一句话就能描述完 diff，就不该走 plan。

比如：改个常量、加条 log、重命名变量、修 typo、往已知位置加一个字段。

这种情况直接输出：

这个不值得走 /plan——它一句话就能说完（把要改的那一句写在这里）。 直接说「改吧」我就动手。

然后 return，本次 skill 到此结束。不要建目录、不要写 research.md、不要「顺便先调研一下」。

放最前面的理由：反模式的成本发生在建目录那一刻。一旦开始写 research.md， 后面每一步都会为「已经开了头」自我合理化，最后用 200 行文档描述一个 3 行的改动。

满足下列至少一条才继续：

• 不知道该改哪些文件，或涉及 3 个以上文件
• 根因不明确，需要先查
• 有多个可选方案要权衡
• 改动会影响已有实验结果的可比性

第 1 步 Research

派 subagent 并行调研

不要自己一个个读文件。 探索会读进大量最终用不上的内容，那些不该留在主 context 里。 派 Explore subagent 并行去查，每个 subagent 一个明确问题，只回报结论和 文件:行号：

• subagent A：X 功能的入口和调用链在哪
• subagent B：数据从 A 到 B 怎么流的，形状/单位在哪一步变
• subagent C：项目里已有的同类实现怎么做的，有什么约定

需要文献背景派 lit-reviewer；涉及历史实验数值去查 research-log.md，不要猜。

主 context 只保留 subagent 的回报，不要把原始文件内容整段拉进来。

写 research.md

路径 docs/plans/<YYYYMMDD>-<slug>/research.md（slug 用小写英文加短横线）。固定四节：

1. 相关文件位置 —— 路径:行号 + 一句话职责。只列真正相关的，不是目录树。
2. 数据如何流动 —— 从输入到输出经过哪些函数，哪一步改变了形状/单位/量纲。
3. 根因假设 —— 至少 1 条，最好 2-3 条互相竞争，每条写明怎么才能证伪。 没验证的写成假设，不要写成结论。
4. 既有模式与约束 —— 已有做法、不能破坏的接口、影响方案选择的历史包袱。

每条断言要么给 文件:行号，要么标 [AI-DRAFT]。猜测必须显式标成猜测。

第 2 步 Plan

写 docs/plans/<YYYYMMDD>-<slug>/plan.md。

精度要求（本模板最硬的格式要求）

每一步必须回答四个问题，缺一个这步就是废的：

1. 改哪个文件 —— 精确到路径，能到函数/行号更好
2. 改什么 —— 「把 A 换成 B」「新增函数 f，签名是 ...」。不要写「优化 X」「重构 Y」
3. 怎么验证 —— 一条可直接粘贴执行的命令
4. 成功判据 —— 看到什么算过。「测试通过」不够，要写清哪个测试、期望什么输出

结构

# Plan: <标题>
关联 research: ./research.md

## 目标
一句话：做完之后什么变成了可能，或什么问题消失了。

## 不在范围内
- 显式列出这次**不做**的事，至少 2 条
- 尤其是那些「顺手就能做」但会让 diff 变大的事
- 这一节是实现阶段用来拒绝范围蔓延的依据，必须写

## Phase 1: <名字>
- 改 `path/to/file.py:120` 的 `foo()`：<改什么>
- 改 `path/to/other.py`：<改什么>
- 验证：`# TODO(填测试命令) tests/test_foo.py -k bar`
- 判据：`test_bar` 由 fail 转 pass，其余用例数量不变

## Phase 2: <名字>
...

## 端到端验证
- 命令：<一条把整条链路跑通的命令>
- 判据：<具体到数字或具体输出>

## 发现但未做
（实现阶段往这里追加，本阶段留空）

分 phase 的原则：每个 phase 结束时代码必须可运行、可验证、可提交。 不能出现「Phase 1 之后代码是坏的，要等 Phase 2 才能跑」。 一个 phase 大到需要超过一轮对话就拆开。

结尾必须有端到端验证

phase 级验证只证明局部没坏。plan 末尾一定要有一条把整条链路走通的命令和判据。 没有这一节的 plan 不算写完。

第 3 步 对抗式审查（不能跳）

plan.md 写完后，派 plan-critic subagent 审这份 plan，明确要求它挑刺：

• 哪一步的成功判据含糊（「能跑通」「效果更好」这类）
• 哪一步的验证命令其实验证不了这一步声称的东西
• phase 之间有没有隐藏依赖，导致中间状态不可运行
• research.md 里的根因假设是否被 plan 悄悄当成了既成事实
• 有没有更简单的方案被漏掉

逐条处理：采纳就改 plan.md；不采纳就在 plan.md 里写一行为什么不采纳。 不要只是把意见转述给用户。

收尾

输出：

1. 两个文件的路径
2. phase 列表，每个一行
3. plan-critic 提了什么、怎么处理的
4. 原话告知用户：「这是你唯一需要认真 review 的东西。看完 plan.md 再 /impl —— 我现在不会开始写代码。」

硬约束

• 全程不改源文件，产物只有那两个 .md。
• 不要自动开始实现。
• 不确定的地方写「不确定」并说明怎么才能确定，别用流畅措辞盖过去。
• plan.md 里出现的任何数值（现状指标、baseline）必须来自 research-log.md 或实测， 并标 [source: run_id]。不要凭印象写数字。