Plan refine

plan-refine — 自省→批判→改进的迭代循环

把一个待打磨的产物(方案/策略/文档/prompt/skill/研究设计/SOP —— 或一个功能/代码改动)反复打磨成经得起推敲的版本:对照真实项目+日志+外部多方信息,反复对抗式批判它。流程是固定骨架;每步怎么执行,取决于产物类型。Step 2 时加载 reference/critique-playbook.md —— 完整的批判攻击角度、波及面映射方法、外部取证来源、防退化战术、learnings 日志都在那里。

---

最小核心(只记三件事就够用)

1. 锚定再批判 —— 先读项目+日志(内部),再去 GitHub/网上取证(外部);没锚的批判作废,困在自己认知里不取证的批判半废。
2. 每轮新角度 + 每条带改法 —— 每条批判 = 在哪儿 + 哪里不对 + 为什么/证据来源 + 怎么改(Self-Refine:定位 + 指令);每轮攻还没用过的角度,重复嚼旧点 = 收敛信号,不是进步(Reflexion 的 degeneration-of-thought)。
3. 诚实停 —— 批判只剩措辞级 / 只在炒旧点没新角度 / 预算用完 / 连续两轮没动实质 —— 任一即停;别凑数。一轮也别太早停:no-findings 的第一轮多半是 grounding 偷懒,不是产物完美。

---

何时用 / 不用

• 用:要把一个产物(方案/策略/文档/prompt/skill/研究设计/SOP)或一个代码改动反复打磨到相对完美的迭代任务;用户说"反复批判改进/坐一小时/迭代到收敛"。
• 不用:一次性问答;只是执行已定好的方案(本 skill 只产出"打磨好的产物 + changelog");纯探索/研究(用 explore / scientist)。

---

输入

• 产物:文档路径/内容,或代码改动(需求 + 目标文件)。只有目标/brief 也行 —— Step 1 起草 v1。
• 锚:项目代码(关键文件、结构、README/CLAUDE.md/AGENTS.md)+ 日志(运行日志、漏斗数据、错误模式、历史 changelog);+ 外部信息(GitHub 现成轮子/别人怎么解的/issue 里的坑、网上最佳实践/数据/竞品/官方文档)。没锚不批判。
• 预算(可选):轮数上限 / 时间("一小时")/ "到相对完美"。默认:跑到收敛。

---

固定流程(骨架 —— 不偏离)

Step 0  锚定 (Ground)
        (a) 内部:读项目+日志,写下"系统/产物现在已经做了什么"——后面批判必须尊重这个现实。
        (b) 外部:主动去 GitHub / 网上取证(现成轮子、别人怎么解的、最佳实践、数据、竞品、官方文档),
            多方交叉印证;记下来当 Step 2 的弹药 + 替代方案来源。
        (c) 读 reference/critique-playbook.md 里的 learnings 段(若有上次跑的教训)。
        省略 (a) → 批判没锚,整个循环作废;省略 (b) → 批判困在自己认知里。
        【一次性】Step 0 把项目/产物读透并记笔记;后面各轮靠笔记,别每轮重读项目(白烧 context)。
        【大产物】产物大到装不下(大代码改动 / 长文档)→ 分节做(一轮一节)或 fan-out(一子 agent 一节/一角度)再合,别硬塞整个进 context。

Step 1  分类 + v1
        判断产物类型:代码/功能改动 → 模式 B;其它(方案/文档/prompt/skill/研究设计/SOP)→ 模式 A;
        混合(方案里夹代码改动、或产物本身是个 skill/prompt)→ 两套都用。
        没有现成产物 → 起草 v1(已吸收 Step 0 的内外信息)。有 → 把它原样定为 v1。

Step 2  反省 & 批判 (Reflect & Critique)  ← 循环核心
        加载 reference/critique-playbook.md。对当前版本做对抗式批判,从【还没用过的角度】。
        每条 = [在哪儿] + [哪里不对] + [为什么 / 证据 + 来源(repo/链接/数据/代码行)] + [改法建议]。
        维护一个"已批判过的点"清单,别重复嚼。鼓励每轮再补一两次针对性搜索补新弹药。
        检验:随便一想能想出的问题、上网一搜能找到的更好做法 —— 都该在这个清单里。

Step 3  改进 / 修订 (Improve / Revise)
        吸收 Step 2 的发现。版本号 +1。文末 changelog 追加一条(本轮批判发现什么 → 改了什么)。
        合法的改进:推翻重来 / 删掉上一轮加的 / 收紧精简(臃肿 = 退化)。
        【ping-pong 守卫】退一个旧改动前先查 changelog:这个点是不是"试过又退过"?是 → 你在横跳,
        停,把真实张力记成给用户的 open question,别反复 flip-flop。
        (注:revert 本身合法 —— 后一轮发现前一轮改坏了 → 回退到上一版,这是【纠错】不是 flip-flop;
         flip-flop 是在【已定的点】上来回。回退也在 changelog 记一笔。)

Step 4  停止检验 (Stop check)
        任一成立即停:① 本轮批判只剩措辞 / cosmetic 级;② 本轮只在炒前几轮旧点、拿不出新角度;
        ③ 轮数 / 时间预算用完;④ 连续两轮产物实质没变(只动措辞);⑤ 达到"相对完美"(下行定义)。
        【"相对完美" =】换视角(critic agent / 别的模型 / 对抗 persona)批判找不到实质问题
            + 产物遵守自己的规则(若是 skill/SOP)+ changelog 讲了个连贯的"越改越好"故事(无 flip-flop)
            + 最小核心确实最小 —— 四条都成立。
        【时间预算是 proxy】agent 看不到时钟:把"~30min"当 ~2-3 个实质轮,"~1hr"当 ~4-6 轮;用户想多/少自己打断。
        【轮数手感】多数产物 3-6 个实质轮就收敛;过 ~8 轮还在找"真问题" → 多半 degeneration(在 re-frame 不是改进),停。
        若是 ② 或 ④ 但你不确定:调 critic agent / /ask 别的模型 / 换对抗 persona,再来一轮确认(往往就证实收敛了)。
        若预算用完:诚实列"还有 X 没解决"。否则 → 回 Step 2。

Step 5  收尾
        往 reference/critique-playbook.md 的 learnings 段追加 1-2 行:这次哪条批判后来证明不对、
        哪个点漏了 —— 下次 Step 0 读。
        输出:打磨好的产物(带版本头 + 文末 changelog) + 给用户逐轮"批判 → 改了啥"摘要。

---

模式分类(Step 1 决定)

• 模式 A —— 非代码产物(方案/策略/文档/prompt/skill/研究设计/SOP):批判勇于提各种可能性、用证据论证出最好的;每轮在产物开头给一段"最小核心";完整攻击角度见 playbook §A。
• 模式 B —— 代码/功能改动("改一点动全身"):每轮先映射波及面(怎么映射 + 查哪些 见 playbook §B)→ 把相关联的部分在同一轮一起改到一致 → 批判稳健性(是不是项目已有的?真解决了还是治标?有没有更小/更稳的做法?漏了哪个波及点?)→ 用户每天依赖的系统就出 diff 让用户定,不直接落地。波及面巨大(碰几十个文件)本身就是一条 finding —— 改动可能太侵入,考虑更小的改法 / 兼容 shim / 分阶段,别英雄式硬编几十个文件。
• 混合 / 元(产物本身是个 skill/prompt,或方案里夹代码改动):两套都用;元批判尤其容易 ping-pong,严守 Step 3 的守卫。

---

硬规则(两模式通用)

1. 每轮必须改实质性的东西,或宣布收敛。 不凑数。

2. 批判必须有锚 —— 内 + 外。 内 = 项目+日志;外 = GitHub/网上多方取证。每条尽量带来源。允许每轮补搜 —— 取证是持续的。

3. 循环里不执行方案、不顺手大改项目。 产出 = 打磨好的产物 + changelog。发现的小 bug 记成 finding,别跑去改(除非那正是本次产物)。

4. 防退化:每轮换角度 —— 重复嚼旧点 = 收敛信号不是进步(degeneration-of-thought);退旧改动前查 changelog 防 ping-pong;炒旧点/没新角度时换视角(critic agent / 别的模型 / 对抗 persona)。

5. 自主跑,默认一直做 —— 但这不是"放飞自我"的许可证。 这个 skill 是给 AI agent 用的:自己决策的范围 = 低风险、可逆、做错了能轻松改回来的选择(选哪个攻击角度、措辞、要不要再补一次搜索、跳过一个小项、收敛了没、"要不要继续/这样行不行/下一轮可以吗")—— 这些自己定、不汇报、别要许可。

   必须先经用户、不许自作主张的(硬线,不是"看情况"):

   • 对外/难撤销的动作 —— 发布到外部(GitHub/网上/发消息)、覆盖或删除文件/数据、改用户每天依赖的生产系统(那种就出 diff 给用户定,见模式 B)、花钱、用真凭据操作真账号。就算你觉得答案很明显也要先确认 —— "我以为他想发布"不算授权。
   • 只有用户知道的事实 —— 签证状态、预算、deadline、那 2 个面试是哪个…缺这个就把产物按分支写出来,继续做不依赖它的部分,别卡住等回复。
   • 真·没有明显最优、且后果大的价值取舍 —— 砸掉整个方向重来、改变核心赌注那一级的。

   汇报节奏:跑完(收敛 / 预算用完 / 卡在上面任一项)才给一份摘要;中途不滚动汇报"我做了 X 现在做 Y"。原则:小事自己利索地做,大事先问;不确定一件事算大算小 → 当大的。

6. 诚实对待收敛 —— 措辞级/炒旧点就说收敛,停;别表演更多轮。但 no-findings 的第一轮 ≈ grounding 偷懒,回去重新锚定。

7. changelog 必须可见,一轮一条,版本递增。本 skill 自己也得有 changelog —— 吃自己的狗粮。

8. 精简、删上一轮加的,都是合法修订。臃肿 = 退化。 本 SKILL.md 保持"流程为主"——长清单/上下文进 reference/(Anthropic 官方:SKILL.md ≈ 10-20 步流程,context 进 reference 文件)。

9. 置信度标 —— 事实(可验证)/ 判断(合理但可争论)/ 未知(需用户输入)分开,别把猜测当事实陈述。

10. 批判格式 = 定位 + 指令(Self-Refine)—— 说清在哪、为什么、怎么改,不是光说"这弱"。

11. 流程固定、执行多样 —— 骨架不变;模式 A/B 决定每步怎么做。

---

输出格式

• 产物本身:版本头 # <标题> (v<N>) + 一行本版相对上版的核心变化;(模式 A)开头一段"如果只做 X 件事"的最小核心;文末 changelog,每轮一条 v<N> (round k): 批判发现 [...] → 改了 [...],末条标"收敛于 v<N>"或"预算用完,未解决 [...]"。
• 给用户:一段简短摘要,逐轮列 Round k 批判: [...] → 改了 [...],让人看到"批判-改进-批判"的轨迹。

---

现成轮子 / 参考

本 skill = Self-Refine(Madaan 2023, arxiv 2303.17651)+ Reflexion(Shinn 2023)+ 多智能体反省 + Anthropic 官方 skill best-practices 的轻量、产物锚定、双模式(A/B)、双停止(相对完美 / 预算)变体。完整出处、各自要点、以及与工具箱里 critic / self-improve / autoresearch / ralph 的区别 —— 见 reference/critique-playbook.md §F。

---

示例触发

• "针对这个方案反复批判、改进,坐一个小时" → 模式 A,跑到时间用完或收敛。
• "升级这个功能,注意改一点动全身" → 模式 B,每轮先映射波及面。
• "把 PLAN.md 迭代到相对完美" → 模式 A,跑到收敛。
• "/plan-refine docs/PROPOSAL.md 项目在 ./src 日志在 ./logs 跑 5 轮" → 锚定 src+logs,5 轮,逐轮 changelog。
• "用 refine 升级 refine skill" → 元/模式 A,严守 ping-pong 守卫。

---

版本 / changelog(吃自己的狗粮)

• v0.1 初版:固定流程 + 模式 A/B + 通用规则。
• v0.2:Step 0 加"外部取证(GitHub/网上多方来源)";批判要带来源。
• v0.3:描述里强调外部取证。
• v0.4(用 plan-refine 跑自己,3 轮):
  • round 1(外部弹药:Self-Refine / Reflexion / Anthropic skill best-practices):加 degeneration-of-thought 守卫(每轮换角度 + ping-pong 查 changelog);批判格式改成"定位 + 改法";把长清单拆进 reference/critique-playbook.md(官方:SKILL.md 只放流程);加 learnings loop(写在 playbook 末尾,Step 5 写 / Step 0 读);停止条件锐化为 4 个并列条件;模式 A 从"方案/proposal"扩到"任何非代码产物" + Step 1 显式分类 + 加"元/混合"情形。
  • round 2:"卡住时换 persona/模型/critic"从"每轮做"改成触发式(只在炒旧点/没新角度时);加"no-findings 的第一轮 ≈ grounding 偷懒";learnings 不单开文件、并进 playbook 末尾(少一个文件);复核 SKILL.md 确实瘦身到"流程+规则+分类",不是迷你版全集。
  • round 3:自洽性复核 —— skill 自己有 changelog ✓、有最小核心 ✓、模式分类 ✓、长度 ≈ 官方建议的流程量级 ✓;无新实质问题 → 暂判收敛。
• v0.5(再跑 2 轮 ≈ 30min,从已宣布收敛后【换新视角】再攻):
  • round 4("完全漏掉的"角度):加 一轮成本/轮数手感(多数 3-6 轮收敛,>~8 轮疑似 degeneration);Step 0 一次性读透项目、后续靠笔记别重读;大产物 → 分节做 / fan-out;"时间预算是 proxy"(agent 没时钟,~30min≈2-3 轮、~1hr≈4-6 轮);操作化"相对完美"(换视角无实质问题 + 遵守自己规则 + changelog 无 flip-flop + 最小核心确实最小);§E learnings 要剪枝(留会复现的);模式 B 加"波及面巨大本身就是 finding";把"现成轮子/参考"长段移进 playbook §F(给每个 add 配一个 cut 防臃肿)。
  • round 5:只剩边际 —— 澄清"revert 合法 ≠ flip-flop"(纠错 vs 在已定点上来回)。无新实质问题 → 收敛于 v0.5,相对完美。
• v0.6(用户反馈,2026-05-12):规则 #5 锐化 —— 默认一直做、低风险可逆的选择自己定不汇报(攻击角度/措辞/补搜/跳小项/收敛与否/"要不要继续");但设了硬线:对外或难撤销的动作(发布、删数据、改生产系统、花钱、用真凭据)、只有用户知道的事实、后果大且没明显最优的取舍 —— 必须先经用户,"我以为他想要"不算授权(用户提醒:这 skill 是给 AI 用的,不是放飞自我的许可证)。不滚动汇报 —— 跑完才给一份摘要。原则:小事自己利索做、大事先问、不确定算大。
• 收敛于 v0.5(+ v0.6 的汇报/自主决策规则)。后续靠 learnings loop(playbook §E)跨次累积,不预先多迭代。