omh-ralplan-driver

OMH Ralplan 驱动器——驱动循环

当你作为调度器负责调度循环时，请将此技能与 omh-ralplan 一起加载。Planner / Architect / Critic 工作者会加载 omh-ralplan——它涵盖他们在每次 delegate_task 调用中的工作内容。此技能涵盖你作为调度器的工作：准备、调度、提炼、审查。

这两种技能面向不同的读者，承担不同的任务。不要将它们合并 ——工作者的上下文十分宝贵；调度器的操作手册不应随每个子 Agent 一起传递。

为什么需要此技能

如果缺乏严谨的编排，Ralplan 收敛的会是内部一致性，而不是真相。Planner / Architect / Critic 三角协作会自我校验——无论你让它处理什么，它都会得出一套自洽的立场，包括错误的框架、过时的来源、 虚构的约束，以及用户已经解决的问题。

只有调度器拥有这样的视角，能够：

• 在调度之前确立原则。
• 编写上下文资料包，为框架争论提供依据。
• 核实事实真相和相关机制，避免子 Agent 将其当作事实。
• 与用户一起迭代资料包——任何非简单需求都有一半来自用户的实际情况，而非阅读资料。
• 将共识提炼成不含审查辅助内容的规范产物。
• 在交付给用户之前执行最终质量把关。

下文提到的大多数失败模式都发生在调度之前。**质量始于准备。**提炼和审查负责保留质量。循环本身只是中间那台配备完善仪表的引擎。

何时使用 ralplan，何时自行思考

在以下情况下使用 ralplan：

• 问题存在多种合理的拆解方式。
• 有一些必须在各个子 Agent 之间贯彻的关键原则。
• 存在调度器独自处理时可能遗漏的横切关注点。
• 用户可能会陷入逐轮提案的循环。

如果工作仅涉及单个文件、单个决策，或解决方案显而易见，则不要使用 ralplan。杀鸡用牛刀本身也是一种失败模式。如果目标模糊，请先使用 omh-deep-interview。

五步操作手册

1. 先确立原则（如果尚不存在）

没有原则的 Ralplan 会产出看似合理的胡言乱语。Planner/Architect/Critic 三角协作会收敛于内部一致性， 而非真相。原则是外部锚点。

一个不错的起点是：在项目根目录创建精简的 PRINCIPLES.md（≤15 条）。每条原则都应起到关键作用，并指出它要防止的失败。将此文件列为每个子 Agent 的必读内容。

如果原则尚不存在，请先确立原则——即使是快速草拟，也胜过毫无原则的 ralplan。文件可以迭代；锚点则不可缺失。

2. 起草上下文包，而不只是提示词

上下文包是存放在 docs/design/<domain>/context.md 中的动态文档。它是本次运行中承载分量最大的单一产物。规划者会阅读它。架构师会阅读它。 批评者会阅读它。无论子 Agent 多么出色，薄弱的上下文包都会导致薄弱的立场。

必需章节：

• 设计问题。 用一个句子提出问题，然后用 2-3 个段落展开。说明输出必须实现什么、必须遵循什么，以及它将作为哪些内容的基础。

• 产物类型声明。 在靠前位置用一个句子说明：“这是设计型的，而非需求型的”——反之亦然。这会迫使编排者在起草维度之前先作出选择，并告知子 Agent 应遵循哪些专业规则（参见 Pitfall 15）。添加成本低，却能在围绕错误框架起草维度之前，暴露形态错误。

• 子维度。 初步列出立场必须涉及的方面。并非不可更改——下方的元问题授权批评者重新审视这些维度。

• 约束。 本次运行必须遵循的原则、指令和已确定的先前决策。

• 范围之外。 本次运行不设计的内容。

• 必读材料。 仅使用绝对路径。子 Agent 无法执行 cd，也无法依据摘要开展工作。按类别分组：原则 + 指令、灵感 / 先例、目标平台、现有代码，以及上下文包本身。

• 争议问题。 列出六到八个最可能出现草率共识的方面，作为批评者的切入点。无需涵盖所有方面。

• 一个元问题。 “这些子维度是否合适？”这会授权批评者质疑框架本身，而这正是批评者能做的最重要的事。没有这个问题，批评者就会停留在框架之内，只检查是否符合要求。

• 完成标准。 给出具体的输出标准。其中一项必须要求回答：“灵感材料中缺少什么？理想版本会有什么而灵感材料没有？”

编排者先起草上下文包并进行审阅，然后在运行循环之前与用户逐项确认（参见 Pitfall 10）。上下文包对质量起着决定性作用。

3. 第一轮顺序执行，第二轮并行执行

第一轮：规划者 → 架构师 → 批评者，严格按顺序执行。每个角色都要阅读先前的输出和必读材料。每个角色都要将具名产物写入设计目录，而不是直接写在工具响应中。

文件命名约定：

• stance-planner.md
• review-architect.md
• review-critic.md

仅当任一审阅者未给出 APPROVE 时，才进行第二轮。规划者进行修订；架构师和批评者通过批量调用 delegate_task(tasks=[...]) 并行重新审阅。这能显著节省实际耗时（一次常规运行的第二轮就节省了约 100 秒）。

第二轮文件命名：添加 -v2 后缀。将第一轮产物保留在磁盘上作为溯源依据——它们能展现循环的推进过程。

三个 APPROVE 即达成共识，循环结束。否则继续迭代；最多进行 3 轮，若仍未达成一致，则注明保留意见。

4. 提炼内容，而不是把原始输出交给用户

达成共识后，规划者的最终立场会在顶部包含一个“Round 2 response map”章节——这是给审阅者用的检查清单，不是给用户看的。删除该部分；保留实质内容。将结果写入 stance.md（不加后缀）。同时保留原始的 stance-planner-v2.md，放在旁边作为溯源依据。

如果产物是需求型的，则提炼为 requirements.md，而不是 stance.md——规范文件名应与产物名词一致（参见 Pitfall 15）。

还要在 .omh/plans/ralplan-<instance-id>.md 写入共识摘要，注明各轮结果、批评者发现的问题、关键设计立场、MV 步骤和文件指针。这是编排者的简短摘要——便于 grep 搜索，也能在会话轮换后保留。

5. 编排者审核，然后提交给用户

编排者的审核是用户看到任何内容之前的最后一道关卡。撰写两份产物，而不是一份：

• brief.md — 用户阅读的内容。决策优先。约 1–2 页。 将已确定的决策放在最前面，明确指出与派发前对话的偏差， 用一段话说明设计最终结果，列出遗留的开放问题和后续步骤。 用户只看这份内容就必须能够作出判断——绝不要迫使他们 先读深入审核，才知道需要决定什么。

• <orchestrator>-review-deep.md — 存档内容。内部讨论、 完整推理、遵从性测试、运行方法观察、层级补充说明，以及 批评者从叙述角度发现的问题。保存在磁盘上，以供追溯，也供 用户偶尔想全面了解时查阅。**默认不阅读。**取代旧版运行中 所称的 <orchestrator>-review.md。

简报用于交付；深入审核用于留档。请将它们视为面向不同读者 的不同产物。

深入审核包含的内容（与之前相同）：

• 是否达到我的标准？（是/否 + 原因。）
• 批评者发现了哪些让我意外的问题。
• 我会温和提出异议的地方——与用户交流时会提及、但不构成阻碍的内容。
• 我预计用户会提出异议的地方——在他们阅读前先提醒他们。
• 这次运行让我对方法有何认识。
• 提炼过程中纳入的限定条件（如有）。

简报包含的内容（决策优先，参见 P26 + 模板）：

• 需要用户作出的决策，逐项编号，并附上我的看法。
• 与派发前对话相比有哪些偏差（具体说明）。
• 一段话说明“设计最终结果”。
• 留待 v2 解决的开放问题 / 实际使用中的摩擦。
• 后续步骤。

如果深入审核质量不佳，就再进行一轮，或完善原则。不要把低于 自身标准的输出交给用户——层级精简依赖于此。简报是检验 精简效果的方式：如果你无法将深入审核压缩成一份清晰、决策优先 的简报，就说明你的层级判断能力并没有你以为的那么强。

深入审核模板见 references/orchestrator-review-template.md， 简报模板见 references/brief-template.md。

常见陷阱（编号 P1–P26）

以下是编排者反复遇到的失败模式，每一条都是惨痛教训得来的。 编号连续，没有缺号。

P1 — 绝不要引用尚未写入的文件

不要在 delegate_task 上下文中写“我接下来会写入文件 X”， 然后立即派发任务。子 Agent 会读取上下文、查找 X，却发现文件 不存在，最终超时或产出有问题的内容。始终先写好引用的文件， 再派发引用这些文件的 delegate_task。

P2 — 超时 ≠ 没有完成工作

子 Agent 有时会报告“超时，0 次 API 调用”，但实际上已经完成 工作，并将数 KB 的输出写入磁盘。出问题的是报告通道，而非工作本身。 重新生成前，先检查磁盘：目标输出文件是否存在？读取它。工作 可能已经完成。多次运行已证实这一点——磁盘上的文件才是事实依据， 而不是工具状态字符串。

P3 — 上下文大小会迅速膨胀

每个子 Agent 在第 1 轮中读取必需文件时，都可能消耗数十万个输入 Token。3 个子 Agent × 2 轮 = 真正的成本。可采取以下措施：

• 如果大型辅助文档只是次要参考，请拆分它们。
• 对第 2 轮审核者，可考虑传递差异内容和 v2 立场，而不是让他们 重新阅读每个文件。
• 如实区分哪些内容是必读、哪些是有用参考——在资料包中 分别列出。

P4 — 批评者必须获准质疑框架

这是最关键的一步。如果上下文包只列出“当前框架内需要推动的事项”，批评者就会局限在当前框架内。明确加入 META 问题。必须告诉批评者：拆解本身也可以质疑。

这能发现那个悄然缺席的原则——没人提及它，是因为所有人都身处遮蔽它的框架之中。没有明确授权，批评者只能发现细节；有了明确授权，批评者才能发现框架。

P5 — 提供有争议的问题作为引子，不要穷尽所有问题

提供六到八个具体的争议点作为引子，数量最合适。再少，批评者就缺乏引导；再多，批评者就会感觉受到束缚。

特别要明确要求：“全面审查所有原则；不要止步于上面的列表。” 优秀的批评者会超越这些引子。引子用于启发，而不是核对清单。

P6 — 具体的反提案胜过标记问题

优秀的批评者会提出具体的替代方案（“使用四个维度：X / Y / Z / W”），而不只是说“考虑采用不同的拆解方式”。在批评者提示词中要求这种形式。含糊地说“考虑其他方案”，只会得到含糊的回应。

这种模式让第二轮规划者能够基于原则采纳或驳回——“这个替代方案成立，因为……”——而不是费力猜测批评者的意思。

P7 — 期待基于原则的采纳，并检验是否盲从

在第二轮中，检查规划者采纳批评者的建议，是因为这些建议本身逻辑成立，还是因为批评者这么说。具体来说，使用反事实盲从测试：

如果一个反事实批评者提出了不同的替代方案，这份辩护是否也会采纳？

如果规划者提出的所有理由同样适用于某个反事实替代方案，那么这就是盲从式采纳——基于模式匹配，而非原则。如果有些理由不适用于其他方案，那么这份辩护就针对所选替代方案——确认是基于原则的采纳。

这项测试应写入第二轮批评者提示词。完整文本请参见 references/critic-goal-template.md。

P8 — 不要将状态文件提交到 git，提交计划文件

.omh/state/<mode>--<instance_id>.json 中每个实例的状态属于会话临时数据。.omh/plans/<file>.md 是正式记录的产物。将 state/ 保留在 .omh/.gitignore 中；提交 plans/。

P9 — 派发侦察任务前，验证事实依据是否为最新版本

如果上下文包让子 Agent 将本地源码检出目录（供应商仓库、克隆的库、外部项目）作为“事实依据”，派发任务前，请确认检出目录确实处于你认为的版本。 子 Agent 会如实引用它们读到的内容；但它们无法知道 main 是否比上游落后了数百次提交。

针对本地源码树派发任务前的检查清单：

cd <source-tree>
git remote -v                                          # confirm remotes
git fetch --all --tags                                 # update refs
git rev-list --left-right --count HEAD...@{upstream}   # ahead/behind
git describe --tags --abbrev=0                         # latest tag at HEAD

如果 HEAD 明显落后于侦察任务所针对的版本，请停止，并选择：(a) 更新该目录；或 (b) 明确将侦察范围限定为“HEAD 中的内容”，并注明版本相关的说法必须标记为无法验证。

只要必读内容包含本地源码检出目录，就在上下文包中添加“事实依据时效性”小节。记录提交 SHA，以及它与设计所依据的上游版本之间的关系。写明“事实依据 = <repo>/@bf196a3f”的上下文包可以验证真伪；写明“事实依据 = <repo>/”的则不行。

如果在运行过程中发现内容过时：不要悄悄更新。应说明这一发现，并与用户协商是 (a) 更新目录并重新运行侦察，(b) 更新目录并就地修改侦察文档，还是 (c) 添加注意事项横幅后继续。

P10 — 派发前与用户一起迭代上下文包

仅凭阅读起草会遗漏只有用户才能指出的方面。 用户对系统的亲身体验会揭示需求，无论阅读多少源代码都无法发现。

规范：

• 根据阅读结果起草上下文包。从源材料中梳理子维度并提出初步争议点。
• 与用户一起过一遍。询问：这样的拆分合理吗？还缺少哪些维度？哪些争议点的权重似乎不足？
• 就地修改。注明变更（“七个维度 → 八个，已在派发前的上下文审查中修订”），让 Planner 知道经过了迭代并予以重视。
• 然后再派发。

跳过这一步，会在 Critic 发现维度缺失时多耗费一轮 ralplan；而用户原本可以在派发前用两分钟指出这一点。

P11 — 不要围绕用户已经定下的问题提出争议点

这与 P10 相邻，却是相反的失败模式。编排者起草争议点时会问“Critic 会质疑什么？”——结果无意中重新开启了用户已经明确决定的问题。

失败模式：用户在 ralplan 之前的对话中说：“目标不只是修复 X，而是为未来的 Y 找到更好的模式。”编排者随后却提出争议点：“我们真的需要这个新模式吗？还是只做针对性修复就够了？”这个争议点会迫使用户重新为已经确立的立场辩护。

规范：

1. **起草争议点前，列出用户已经确定的承诺。**阅读促成 ralplan 的对话。写下用户在草案开始前已经声明、主张或选择的内容。将这些内容视为不可协商的约束，除非用户主动重新讨论。

2. **逐一对照已确定事项检查争议点。**如果某个争议点会重新开启已确定的问题，就不要把它写成争议点。将其写成约束，或把其中的承诺纳入另一个争议点的前提。

3. **作出承诺后，合适的争议点应当是：“在用户已经承诺的方向下，这一承诺内部应当采用怎样的形态？”**而不是“用户当初是否应该作出这个承诺？”

4. **用户在审查中指出这个错误时，应从框定问题的层面接受修正，而不是只改措辞。**通常还会有一些根源相同的相关争议点或约束。宣布修复前，先全面检查一遍。

P12 — 派发涉及路径的目标前，先确定文件系统布局

如果上下文包引用的目录布局让人觉得“应该整理一下”——例如目录杂乱、子目录随意、带有“v2”后缀，或项目与事件混淆——先整理，再派发。

如果先派发、后重构：

• 子 Agent 的输出会落入即将删除的目录。
• 必需阅读路径将无法解析。
• 全面重新锚定会变成第二轮返工，而不是进一步完善。

派发涉及路径的目标前，请完成以下检查：

1. 列出目标引用的目录布局。
2. 检查是否存在目录杂乱和命名偏差。
3. 如果发现问题，询问用户——他们往往早已对此感到困扰，只是还没提出来。派发时正是询问的好时机。
4. 如果用户同意，先重构。确认所有绝对路径在新布局下都能解析。直接更新 context.md。
5. 然后再派发。

额外好处：在起草过程中整理目录，往往会暴露设计本身缺少的维度，因为整理会重构设计所处的概念格局。

P13 — 核实外部批评的前提，不要将其当作约束照单全收

当 ralplan 回应外部批评（私信、Bug 报告、评审评论、issue）时，批评中包含诊断（哪里有问题）、处方（应该怎么做），通常还包含一个前提——对当前状况为何如此的断言，而批评者并未核实这一点（“我怀疑原因是 Z”）。

如果你把未经核实的前提当作既定约束，就会围绕一个幻影搭建整套立场。这个幻影约束立场感觉上会很合理，能通过 ralplan 对内部一致性的审查，却只会在面对现实的时候崩塌。

纪律：

1. 标记外部批评者提出的每一个未经你核实的前提。前提是“关于当前代码为何如此的断言”——不同于诊断（哪里有问题）或处方（该怎么做）。

2. 在上下文包中添加一个 “待核实的前提” 部分，列出每个已标记的前提，并附上：逐字引用的说法、批评者对此的描述、提供的证据（通常是“没有／仅为猜测”），以及规划者应打开以进行核实的绝对路径。

3. 明确指示规划者：在围绕任何前提进行设计之前，先逐一核实。如果某个前提不成立，就明确指出，并根据实际约束重新制定方案。

4. 第一轮批评者也应将前提是否有依据作为一项独立检查，与质疑问题框架分开进行。

该部分示例：

## Premises to verify (pre-Planner)

The critique this run responds to supplied these premises without
evidence. Verify each before designing around it.

- **Claim:** "<verbatim>"
  **Source:** <critic's statement>
  **Evidence supplied:** none / partial / speculation
  **Verify by opening:** <absolute paths>
  **If true:** the design honors constraint C<n>.
  **If false:** the design is free of constraint C<n>; revisit.

P14 — 必读内容必须涵盖代码库中相邻的既有机制

让某个立场“拿到三个 APPROVE 却仍然错了”的最常见原因是：规划者为一个相邻问题设计了新机制，而现有代码库早已解决了这个问题。由于没人指出现有方案，子代理便设计了并行构建方案。

开始派发之前，请根据以下问题审核必读清单：

这棵代码树中是否已有解决我们要设计的问题之相邻问题的代码？如果有，必须将其列入必读内容——即使设计最终可能不会用到它。

具体来说，请搜索：

• tools/、agent/、cli/ 中的同步／更新／清单引擎。
• 所有匹配 *_sync.py、*_manifest*、bundled_* 的内容，以及名称中带有 update／reset／migrate 的内容。
• 涉及该领域的现有 CLI 子命令。其实现包含关键模型。
• optional/、migration/，以及以往处理过此问题的任何位置。

在起草上下文包时，花两分钟用 search_files 搜索 sync／manifest／update 相关关键词，远比第二轮返工，或让一个立场进入实际使用后被外部协作者用一句“我关闭了自己的方案，因为系统已经实现了这个功能”推翻要划算得多。

**现场信号：**你遗漏了相邻机制，最可靠的迹象是外部协作者（PR、私信、issue）关闭或转向相关工作，并用一句话说明他们正如何绕开某个问题。出现这样的信号时，**在为该立场辩护之前，先在代码树中搜索提到的系统。**这通常会让该立场自行瓦解。

P15 — 需求类产物有其专属规范

“设计立场”和“需求文档”是不同的产物。默认的 Planner 模板会生成立场。当产物是需求（技术无关的 NEEDS，而非设计立场）时，必须改变三件事：

1. 命名。 提炼后的输出是 requirements.md，而不是 stance.md。来源文件仍使用 <artifact>-planner.md / -v2.md（保持模板命名一致），但交付给用户的规范文件名应与产物名称一致。

2. 上下文包中的规范规则（对需求类运行至关重要）：

   • 规则——要写需求，而非功能。 好：“系统需要持久化的第一人称知识。” 不好：“系统使用 me.md 存储身份。”
   • 规则——每一项都要有内联引用。 每项需求都要附带来源标签，以及 file:line 引用、缺口引用，或原则 + 已命名失败模式引用。
   • 规则——宁缺毋滥，不要编造。 诚实精简胜过冗长整齐。开放问题就保持开放。对需求而言，完整性作秀就是失败模式。
   • 规则——将需求与数量／形式分开。 “三个文件”不是需求；“三种不同的自我认知类型”或许是。
   • 规则——禁止类比推导功能。 “产品 Z 有功能 W，所以我们也需要它”不是需求。
   • 规则——Critic 可以中止循环。 合理的 Critic 结论可以是：“需求目前还无法定稿；以下是需要先解决的事项。” 对有缺陷的产物，REQUEST_CHANGES 并说明“无法闭环”，比 APPROVE 更妥当。

3. 来源本体论。 需求需要使用能区分以下内容的来源标签：源系统实际做了什么、它应该做但没有做什么（可见缺口），以及 某项原则要求什么，但尚无可运行系统验证过。每项都要加标签。若混在一起而不加标签，就会掩盖证据充分与薄弱之处。

当产物是需求时，除了引擎代码，还要让子 Agent 查阅底层／运行时产物（技能、提示词、约定、README）。只阅读引擎的需求类运行会遗漏一半证据——实际使用中的产物往往承载着与源代码同等多的信息。

P16 — 在第二轮应用反事实尊重度测试

当 Planner 采纳了 Critic 在第一轮提出的反建议时，要专门测试这种采纳是否出于原则（该替代方案本身有充分理由），还是出于顺从（仅仅因为 Critic 这么说才采纳）。

强化后的测试：如果是另一位 Critic 提出了不同的替代方案，Planner 的辩护理由是否也同样支持该方案？

• 所有理由都能套用 → 泛泛引用原则，属于顺从。在依据薄弱时给出 REQUEST_CHANGES；要求具体说明为何删掉这一项。
• 部分理由能套用，部分不能 → 辩护具有针对性。确认是基于原则的采纳。
• 没有理由能套用 → 这是异常有力的原则性辩护。

此内容应纳入第二轮 Critic 提示词。完整模板见 references/critic-goal-template.md。

P17 — “需要与用户对话”是合理的第一轮结论

有时，第一轮 Critic 会提出一个子 Agent 从根本上无法解决的本体论问题——这需要用户基于原则作出承诺，而不是让子 Agent 进行更多推理。

在第一轮 Critic 提示词中，将其列为第四类结论：

user-conversation-required: <简明问题> —“这个问题需要用户基于原则作出承诺，而不是让子 Agent 继续工作。问题如下，简明扼要。”

触发此结论时，编排器会升级处理、获取答案，并将其作为原则性指示写入第二轮 Planner 提示词（而非“请考虑”）。这比中止更快，也符合恰当的决策层级。

P18 — 在轮次之间让用户引导，可以重塑设计空间，而不只是做出定论

这比 P17 的模式更有力。在两轮之间向用户展示 Round 1 Critic 发现的问题时，用户的回应可以：

• 做出定论，解决一个单一的本体论问题（小问题）——将其编码为 Round 2 的方向。
• 重塑整个设计空间（大问题）——新增层级，提出循环原本无法触及的新方向。

在展示问题时，不要预先将问题缩窄成二选一。坦诚地说明问题所在以及周围的设计空间。如果用户看到了循环遗漏的内容，就让他们重塑设计。

展示容易引发重塑的问题时，在问题说明末尾加上：“我有什么遗漏吗？”——这就是授予重塑空间的许可。没有这句话，用户可能会按给定的二选一作答，从而错过重塑的机会。

当用户重塑设计时，要将他们提出的每个方向都作为有原则的方向，写入 Round 2 Planner 提示词。编排者在展示问题时的职责是倾听，而非倡导。

重塑模式有一个明显特征：用户的回应以重新界定问题的措辞开头（“第三个层级是 X”），或否定问题的框架（“就这个情况而言……”）。出现这种情况时，你面对的是重塑，而非定论。不要试图把重塑的内容塞回你提出的二选一中。

P19 — APPROVE_WITH_PROVISO：第四种 Round 2 裁决

默认的裁决选项（APPROVE / APPROVE_WITH_RESERVATIONS / REQUEST_CHANGES / REJECT）有时会留下空缺：有些小型的明确补充必须纳入规范产物，但又不足以启动 Round 3。

将 APPROVE_WITH_PROVISO 设为第四种 Round 2 裁决——适用于包含两到四项小型明确补充的裁决（例如缺失的原则说明、契约澄清、故障处理说明），这些内容应在提炼过程中纳入规范立场。

与 APPROVE_WITH_RESERVATIONS 区分开来：保留意见是供编排者权衡的说明；附加条件则是规范产物必须包含的具体修改。

适合使用 PROVISO 的情况：

• Round 2 发现的问题属于表层补充（新增单个章节、明确原则名称、补充缺失规则说明），但又关系重大。
• Critic 可以在评审中写出附加条件的文本（或足够接近的版本），使提炼只需机械地纳入内容，无须重新设计。
• 编排者确信可以纳入这些附加条件，而不破坏立场的平衡。

不要用 PROVISO 来规避实际需要 Round 3 流程的改动。如果附加条件会影响多个章节、改变一项关键决策，或需要单独进行一致性检查，就应使用 REQUEST_CHANGES，而不是 PROVISO。

PROVISO 的提炼规范：

1. 按主题将每项附加条件放入所属章节——不要一股脑加到末尾。
2. 纳入之前，去除 Round 2 评审者的辅助内容（回应映射、自评裁决）。
3. 如果附加条件新增了可测试行为，请更新测试列表。
4. 在编排者评审中注明纳入内容的来源： “Critic R2 PROVISO：X。已作为 纳入 §N。”

这样可以如实保留来源记录：规范立场是共识产物，而编排者评审则记录了哪些内容被纳入，哪些内容被暂缓。

P20 — 种子化的争议点可能在上下文迭代期间被扼杀

P10 强调在派发前与用户迭代。P10 讨论的是用户补充维度，或质疑循环遗漏的内容。

反过来也成立：用户的框定方式可能扼杀编排器作为承重项播下的争议点。

模式：编排器在循环的框架内拟定争议点。用户提出一个循环无法触及的框架（“这也是 X 的试金石”，“我们已经决定采用这种模式，不再讨论是否采用”）。在循环框架内有意义的争议点，到了用户的框架内就变得不合逻辑。

应遵循的原则：

1. 用户在上下文迭代期间重新框定问题时，逐一审视所有争议点，并询问：在新框架下，这个争议点是否仍然成立？ 将虚构的争议点标记为待删除。

2. 不要通过修改虚构的争议点，把它软性扼杀并改成别的内容。 如果争议点是“我们是否需要这个新机制”，而新框架表明“需要，我们正在构建它”，就不要把争议点改写成“这个机制应该放在哪里”。那是另一个争议点。将其作为新的 C-id 添加；让原争议点自然结束。

3. 重新框定通常会带来循环无法预先提出的新争议点。 P10 讲的是这一面。P20 讲的是删除这一面。

4. 在上下文包中记录被扼杀的争议点。 可以添加“上下文迭代期间被扼杀的争议点：”小节（有利于追溯来源），也可以对 context.md 文件进行版本控制，以 diff 作为记录。

为什么这是一种独立的陷阱，而不是 P10 的子情况：编排器在迭代期间倾向于增加内容（更多争议点、更多维度、更多必读材料），因为增加会让人觉得更周全。删减同样是承重环节，而且更难做到，因为这要求你承认自己写的内容形状不对。

P21 — 两轮都必须寻找悄然缺失的行动

第一轮最重要的行动是捕捉悄然缺失之处——某个从未提及的原则，某个因为所有人都身处同一框架而被跳过的维度。META 问题和原则审计会触发这一检查。

第二轮也有自己的悄然缺失之处。第一轮的发现已经落地；立场已经重新组织；现在有什么悄然缺失？ 再次逐一检查所有原则。新立场有新的框架，其中也可能悄然缺少某些内容。

在第二轮 Critic 提示词中添加：“现在，第一轮的发现已落地到第二轮中，是否出现了新的悄然缺失原则？再次逐一检查所有原则。”

循环的职责是在两轮中都找出这些内容。第一轮的悄然缺失是结构性的。第二轮的悄然缺失是契约性的——通常涉及协作、错误处理，以及新结构默认存在却未明说的边缘情况。

P22 — 派发功能领域 ralplan 前，审查父级立场的审定状态

功能领域 ralplan（较大设计树中的子领域 ralplan，例如在已有 docs/design/<parent-domain>/stance.md 的项目中使用 docs/design/<sub-domain>/）从父级立场继承其设计基础。如果父级立场包含新设计将要覆盖的明确立场，那么先派发功能领域 ralplan，要么通过子领域运行重新争辩父级立场（层级不当——功能领域 ralplan 应将父级立场视为约束，而不是争议对象），要么默默覆盖这些立场（更糟——覆盖内容被埋在功能领域的产物中，未来读者无从得知应去哪里查找）。

如果父级立场未经审定，这个陷阱就会加剧：它在之前的 ralplan 运行中获得了三方 APPROVE 共识，却从未经过用户与编排器的同步审查。这样的立场包含一些可能已经与用户商定、但实际上并未定下来的内容。基于未经审定的父级基础派发新的功能领域 ralplan，就像在流沙上设计。 还有一个相关的陷阱：父级立场经过了审查，但撰写时尚无实际使用证据，而这些证据是在当前会话中浮现的。新的设计讨论已经重塑了父级应有的内容，此时调度功能领域的 ralplan，会把这种重塑写入错误的文档（功能领域立场，而非父级立场）。

调度任何非顶层 ralplan 前的预检：

1. 沿设计树向上检查。 从拟定的子领域目录开始，沿 docs/design/ 向上查找——是否存在父级立场？是否存在跨领域立场？是否存在与之重叠的兄弟领域立场？

2. 检查每项父级立场的审查状态。 是否曾与用户同步审查（存在 <orchestrator>-review-deep.md，且讨论过 brief.md）？还是 plan.md / 同等的前瞻文档中列出了尚未执行的“审查此立场”关卡？

3. 逐项核对父级立场中的观点与本会话的重塑内容。 尤其是：用户在当前会话中提出的任何重新界定，以及迭代期间被否决的争议事项列表。它们是否与父级立场中的明确观点相矛盾？

4. 如果对 (2) 或 (3) 的回答是肯定的，正确做法有以下几种：

   • 先转向审查父级立场。 编写父级审查关卡所要求的准备文档（例如 <parent-domain>/stance-review.md），将本会话的证据作为新的观察视角纳入其中，与用户同步执行审查关卡，然后基于已修正的父级依据调度功能领域 ralplan。

     子情况——准备文档已存在，但尚未完成。 父级审查关卡的准备文档可能已在更早的会话中写入磁盘（例如，stance-review.md 中的 Lens 1–3 几周前就已撰写），但从未逐项讨论。不要重写——添加一个新的观察视角，以当前会话的证据为依据。这样既保留了此前观察视角的来源，又能将修正范围限定在实际新增的内容上，还能让审查过程按章节逐项进行。可参考的信号：你发现一个 stance-review.md，其中包含此前注明日期的观察视角，以及一份列出从未得到解答的问题的“建议会话顺序”。添加 Lens N+1，并注明日期作为标题；在文件的 frontmatter 中说明此前的审查曾被推迟；在同步关卡中逐项讨论所有观察视角（新证据可能会让旧问题不再成立；P20——预设的争议事项可以被否决——同样适用于上级）。

     以实际使用证据为依据。 如果当前会话中的重塑源于实际使用证据（父级立场撰写于系统实际运行之前，而现在真实使用揭示了哪些内容并不成立），请在新的观察视角中明确说明。实际使用证据的认知权重不同于侦察证据——它是对失效模式的一次性证明，而不是“有一种可能适用的模式”。明确指出证据类型；证据类型清楚时，用户的审查决定就更有依据。

   • 明确说明覆盖内容，并通过父级处理。 如果用户提出的重塑确实应作为对父级立场的修订，而非功能领域设计的一部分，则在一次提交中将修订写为父级修正，完成审查后，再调度功能领域 ralplan。

   • 向用户确认该覆盖是有意为之，且范围仅限于功能领域。 这种情况少见，但确实存在——有时功能领域设计确实需要父级立场未曾预料到的观点；正确做法是将该观点的适用范围限定得较窄，并在功能领域的 context.md 约束中注明。提交前先取得用户确认。 错误的做法是直接派发功能领域的 ralplan，让循环来发现上级立场冲突。Critic 一定会发现这一点（这正是 META 问题的作用），但这一轮却浪费在了产出内部自洽、最终又必须丢弃的功能领域工作上。预先检查可以避免浪费这一轮。

**这个陷阱刚刚出现的现场信号：**你为一个子领域编写 context.md，按要求检查相关源文件，却发现上级的 stance.md 对相同问题持有的立场与对话一直在推进的方向相反。如果你发现自己在想“我要发起一场竞赛，重新讨论这个上级立场”——停下。重新讨论上级立场并非功能领域竞赛，而是修正上级立场。调整方向。

这个陷阱介于 P10（派发前与用户迭代完善上下文）和 P11（不要针对已定论的问题发起竞赛）之间。P10 关注派发前补充用户掌握的信息；P11 关注不要在同一设计领域内重新讨论用户已经定下的事项。P23 关注不要悄然跨越设计领域的边界。

P24 — 委派以获得全局视角行之有效（此方法背后的原则）

这就是整个技能的核心原则。当用户原本会陷入逐轮提案循环时，应提升视角：

• 提炼原则 → 委派深入工作 → 提炼要点 → 审查。

第一次把 ralplan 执行好，最终形成的立场会比提案—纠正模式所能产出的任何内容都更有力，而且用户可以在循环期间暂时离开。这正是编排者带来的价值，也说明编排者的严谨比工作者的聪明才智更重要。

如果你发现自己和用户在一个涉及多项决策的项目中陷入逐轮纠正循环：停下。提炼原则。运行 ralplan。审查。交付。

P25 — 不要陷入循环的漩涡；保持质疑，而非顺从

编排者角色存在的唯一理由是：站在工作之上，这样你就能以一个高度派发任务、以另一个高度进行审查。整套机制——上下文包、派发的子 Agent、明确命名的裁决、要点提炼、编排者审查关卡——都是为了让你保持清晰与判断力，而框架内的子 Agent 无法做到这一点。

这个陷阱所描述的失败模式是：编排者被拉下去，跟随循环降低视角，因为循环的输出看起来很有意义。表现如下：

• Critic 提出了一项你无法迅速驳回的反提案，你的本能是把它作为问题抛给用户，而不是从更高视角作出判断。
• 你发现自己认可了深度表演，因为你身处漩涡之中，而漩涡看起来很严谨。
• 立场不断扩展范围（增加第 14 条原则、根据第 1 轮发现的问题开启新竞赛、冒出“我还应该……”），而你没有删减，反而接受了这些扩展。
• 你觉得第 2 轮是必不可少的，因为“必须处理”这些发现，而不是因为它们确实关系重大。
• 你发现自己在循环内编写内容（雕琢措辞、提出重新构思），从派发者被拉成了工作者。

结构性解决方法是保持质疑，而非顺从。用户让你担任编排者所给予的信任，是要让你运用，而不是留着不用，直到用户通过纠正来重新激活它。

执行纪律：

1. 面对 Critic / Architect 的任何发现，首先要用自己的判断，而不是询问用户。阅读这项发现。用自己的标准衡量。如果这是深度表演，就从更高视角驳回；在编排者审查部分说明理由。如果它确实关系重大，就明确说明缘由并将其纳入第 2 轮。绝不要首先把问题抛给用户，问“我们该怎么办？”——那就是顺从。

2. 留意形而上学层面／治理层面的陷阱——例如循环产生的「收敛是 X 的行为」或「这需要第 14 条原则」之类的主张。这类内容极少适合写入特定功能领域的 ralplan。Critic 应该质疑框架（P4 元问题），但质疑框架的结果很少属于规范立场——它们应写入协调器评审，说明「循环提出了 X；以下是它为何不构成立场变更」。

3. **如果立场的篇幅超过预期的约 50%，就停下来问问原因。**篇幅是一个信号。如果设计问题是「为现有系统扩展一个同类实例」（P12 连续性），立场就不该从第一性原理重新推导整个系统。如果你发现自己正在读 5000 多字的新教条，而原本应该只有约 1500 字的「先做这个，再做那个，接着做那个」，说明循环已经失控，而你也陷在其中。

4. 用户提出的连续性检查问题是个信号。如果用户读完你产出的内容后回应「这似乎过度设计了」／「你把事情弄得太复杂了」／「我们只需要扩展 X」——这就是对抽象层级的修正。正确做法不是将用户的修正纳入第 2 轮，而是结束本次运行，转向完全不同的抽象层级（通常是：先明确需求，转到 ralplan 以下的经典层级）。

5. **如果设计阶段产出了设计表演，就转向需求。**需求与技术无关、精简，并能形成约束范围，让设计阶段的内容可以切实保持精简。P15 指出需求和立场是不同的产物；这个陷阱进一步说明了这一点——面对冗长的立场，有时正确做法是退回到本应作为立场撰写依据的需求层，而不是继续推进到下一轮。

6. **如实撰写协调器评审。**如果循环产出的仪式感多于严谨性，就在评审中直说，并选择在收紧范围后重新运行，或转向其他方案。「不要把低于自己标准的产出交给用户」这一准则在此尤为重要：抽象层级的协调取决于你是否如实说明循环产出了什么。（这个陷阱刚触发时的信号：你正准备写「循环提出了一些有趣的问题」或「 可能想对此发表意见……」——这两种写法都说明协调器退回了用户所在的抽象层级。协调器评审的职责是应用你自己的标准；如果未达标，评审就应指出这一事实，而不是让用户来决定。）

协调器获得的信任，正是让它做出判断。运用判断力就是它的职责。把每个陷阱都作为问题抛给用户，会让职责倒置，变成「用户的子 Agent」——这正是 ralplan 旨在避免的逐轮纠正循环（P24）。

P26 — 优先交付决策；深度评审留档即可

编排器的深度评审（<orchestrator>-review-deep.md — 见步骤 5）内容全面：轮次统计、批判者发现的问题、 我提出异议之处、我认为用户会提出异议之处、 本轮运行对该方法的验证、视角高度补充说明。它 很坦诚。但当你需要用户做出决策时，它并不适合交给用户。

本条实践陷阱所指的失败模式是：编排器写出一份 出色的深度评审，用户读完后表示，这份评审“内容全面、信息密集，却又出奇简短……我读了很多细节，却有些迷失和疏离。我真的需要你重新给我一组需要我做出的决策，即使这些决策与我们讨论的不同，也请说明原因。”

换句话说：深度评审暴露了用户已经信任你会处理的内部讨论。它要求用户重新走一遍这个循环已经收敛好的推理过程。它把展示你的工作过程（深度评审做到了这一点）和告诉我做出判断所需的信息（这需要另一份材料）混为一谈。高管拿到深度评审，无法据此做出判断；拿到简报则可以。

规范：

1. 在编排器评审步骤准备两份材料，而不是一份。 深度评审留档（保留来源信息和坦诚的自我评估）。简报用于交付。操作手册的步骤 5 对两者都有说明；请遵照执行。

2. 简报应以决策为先。 开篇列出用户需要做出的决策，并编号。对于每项决策，都要说明你的看法以及备选方案。用户可以浏览、决策、回复——无需阅读深度评审也能知道自己要做什么决定。

3. 明确指出与事前讨论的不同之处。 用户花费精力，事先与你梳理了重点、细微差别和注意事项。如果循环得出的结果与讨论内容不同，请在简报中说明原因。隐藏偏差比坦承偏差更快地侵蚀信任。

4. 用一段话说明设计最终方案，而不是八段。 深度评审中关于“立场最终如何确定”的 5–8 段阐述应留在深度评审中。简报只需一段，让读者在决策时能记在工作记忆中。

5. 待解问题和后续步骤应放在简报中。 这些内容需要用户采取行动。内部讨论（遵从性测试、视角高度观察、为技能命名实践陷阱）只应出现在深度评审中。

6. 简报是检验视角高度的标准。 如果你无法将深度评审精简为一份清晰、以决策为先的简报，说明你的视角高度并没有你以为的那么高。 写出简报；如果内容散漫，这就是一个信号——不是让你交付更长的简报，而是重新提炼深度评审，直到简报清晰为止。

7. 用户只读简报，这是成功的标志，而不是失败模式。 很多次运行中，用户永远不会读深度评审。这很正常。深度评审用于追溯来源；简报用于交付。

此实践陷阱刚刚触发的信号：用户读完你交付的内容后表示自己迷失、疏离或无法做出判断。不要通过给深度评审添加更多内容来应对。 应从中提炼一份简报，并修订技能，让后续运行默认以简报作为交付材料。

同样的框架也适用于派发前——简明扼要，不要提问

上述以简报作为交付物的原则适用于提炼后的交接。同样的总统简报框架也适用于更早的派发前决策时刻（P10 步行、P18 会话中途重构、前提预先达成一致、多问题批次）。这里的失败模式与之对称：编排器把开放式问题抛给用户——“你觉得 X 怎么样？”、“我们应该选 Y 还是 Z？”——而不是提供结构化简报。用户不得不从头开始分析；编排器则避而不谈自己的立场。

派发前的原则与派发后相同，只是要压缩形式，以适应行内流程。每份决策简报按顺序包含四个部分：

1. 要决定的问题。 用一段话说明要决定什么。具体明确，不要铺垫。
2. 利害关系。 用两段简短的话说明权衡。说明两个选项各自的代价和收益，以及各自可能导致的失败。如果权衡并不均衡，就不要假装均衡——明确指出哪一方存在不对称。
3. 我的建议。 先用一句话给出建议，再列出 2–4 条理由，每条理由用一句话说明。编排器要承担起责任——不要躲在“由你决定”后面。如果确实没有建议，那就属于另一种情况（先澄清，再决定）；请明确说明。
4. 后续影响。 说明具体后果：会修改哪个文件、哪些设计决策会连锁影响、后续哪些事情会变简单或更困难。

派发前采用这种做法的原因：

• 用户无需重新分析即可批准（“是”／“全部三项”／“开始”）。大多数派发前决策，只要编排器正确阐述，用户就会同意。
• 当用户确实提出异议时，异议会很明确——双方有共同的讨论框架。
• 编排器不得不真正表明立场。*“你觉得呢？”*让编排器可以回避承诺；简报格式则要求编排器提出建议。

何时在派发前提供简报：

• 派发前达成一致的事项（否则会成为第一轮争论焦点、且影响重大的前提）。
• 用户改变架构基础时的会话中途重构（P18）。
• 多个相互独立的决策集中出现时的多问题批次。

何时不要提供简报：

• 单步机械性决策（“提交这个？”——直接提交即可）。
• 用户已经做出决定的事项（不要重新争论）。
• 确实需要讨论而非批准的开放式问题（“v12 的主题是什么？”——这需要讨论）。

格式就是原则。 简短的简报可以压缩（每部分一段），但即使规模很小，结构——利害关系、建议、后果——仍不可或缺。提炼后的简报和派发前简报，是编排器同一做法的两个方面：表明立场，说明后续影响，让用户在共同的框架下批准或提出异议。

请参阅 references/brief-template.md，了解结构模板。

这一注意事项也消除了前文（P19，即编排器审查模板）中的定义歧义：这些章节所说的“编排器审查”，指的是深度审查（<orchestrator>-review-deep.md）。但书仍会纳入深度审查的提炼部分；除非其中某条上升为需要用户决策的事项，否则简报无需提及。

delegate_task 目标模板

[omh-role:planner] <one-line goal>

## Required reading (open these files, do not work from summaries)

Absolute path base: `/.../project/`

<ordered list of files, grouped by category: principles, directives,
inspiration findings, existing-code, context package>

## <Design sub-dimensions, constraints, out-of-scope>

## Questions you must actively contest

- **(META) Are these the right sub-dimensions?** ...
- <six-to-eight specific seed contests>

## Output

Write to: <absolute path>
Structure: <named sections>
Word count target: ...
End with verdict: APPROVE / REQUEST_CHANGES

确保目标自成一体。子代理没有任何先前上下文。

references/ 中提供了可重复使用的完整模板：

• references/planner-goal-template.md — 第 1 轮规划者（含 Requirements 变体和 Lived-moments 搜寻清单）
• references/architect-goal-template.md — 第 1 轮架构师
• references/critic-goal-template.md — 第 1 轮和第 2 轮批评者 （最重要的模板——批评者负责产出质量）
• references/orchestrator-review-template.md — 最终质量关卡

尖括号中的变量因领域而异。保留结构； 每个章节都有其存在的价值。

ralplan 领域的文件布局

docs/design/<domain>/
├── context.md               ← input, reviewed by user
├── stance-planner.md        ← Round 1
├── review-architect.md      ← Round 1
├── review-critic.md         ← Round 1
├── stance-planner-v2.md     ← Round 2 (with response map)
├── review-architect-v2.md   ← Round 2
├── review-critic-v2.md      ← Round 2
├── stance.md                ← distilled from v2; canonical user-read
├── brief.md                      ← decisions-first, what the user reads
├── <orchestrator>-review-deep.md ← orchestrator's archive deep review
└── (later) implementation-plan.md

.omh/plans/ralplan-<instance-id>.md — 简短的共识摘要， 与设计目录分开。位于设计产物沿袭之外。

通过 omh_state 跟踪状态

omh_state(action="write", mode="ralplan", instance_id="<slug>", data={
    "goal": "...",
    "round": 1,  # or 2 / 3
    "phase": "context-gathering | round-N-<role> | complete",
    "consensus": False,
    "plan_file": ".omh/plans/ralplan-<slug>.md",
    "round_1": {"planner_verdict": "...", "architect_verdict": "...", "critic_verdict": "..."},
    "round_2": {...},
})

这是可在会话中断后恢复的状态。如果协调者会话中断， 下一个会话会读取此状态并继续。

协调者的「完成」标准

• 达成三方 APPROVE 共识（或最多进行 3 轮并附带注意事项；或 达成 APPROVE_WITH_PROVISO 并落实附带条件；或 提出并解决需要与用户沟通的问题）。
• 写好规范的 stance.md（或 requirements.md），不含 审阅辅助材料。
• 写好 .omh/plans/<file>.md 共识摘要。
• 写好 <orchestrator>-review-deep.md——诚实、具体，不 流于表面（归档／溯源产物）。
• 写好 brief.md——以决策为先，约 1 页，供用户 阅读并作出判断（P26）。
• 提交一次，包含领域产物和状态 gitignore。
• 提交说明写明：批评者发现的问题、达成的关键立场，以及 已准备好在用户签字确认后执行的 MV。

维护自己的运行日志

此技能通过修补缺陷不断完善。每次 ralplan 运行后， 都要询问：

• 是否出现了符合现有缺陷模式的失效模式？用新的证据加以强化—— 为补充内容注明日期。
• 是否出现了不符合任何现有缺陷模式的失效模式？ 添加新的缺陷模式（P23、P24……）。清楚地命名失效模式，给出 具体示例，并列出规范规则。
• 是否有某项规范格外有效？将其从一次性成功 提炼为有名称的模式。

只有修补此技能，它才会在每次运行后变得更好。每次协调者遇到意外情况后， 如果技能没有得到修补，就会成为负担——听起来信心十足，却已过时。

将自己的运行日志保存在技能之外的某处（你的基底、 项目笔记、wiki）：日期、领域、轮数、意外情况、修补内容。不要让此技能变成会话日志；它是操作手册，不是日记。

不可丢失的内容（若必须凭记忆重新生成此技能）

最重要的见解：**必须授权 Critic 质疑框架本身。**如果上下文包中没有 META 问题，Critic 就会受限于框架之内——检查是否合规，而非检验是否属实。加入 META 问题后，Critic 就会成为推理伙伴，能够发现 Planner 和 Architect 因身处框架之内而看不到的原则缺失。

这正是让 ralplan 优于编排器与用户之间任何提案纠错循环的关键举措。此技能中的其他一切，都是为了支持这一举措。

第二重要的是：**具体的反提案胜过标记出来的顾虑。**优秀的 Critic 会提出具体的替代方案，而不只是说“考虑采用不同的分解方式”。Critic 提示词必须鼓励这种回应方式。随后，Round 2 的 Critic 会检验是否出于原则而采纳，而非出于顺从。

第三：**编排器审查是最后一道关卡。**不要把低于自身标准的输出交给用户。如果立场不够有力，就再进行一轮，或强化原则。精简版高度摘要有赖于此。

第四：**准备工作占了一半价值。**质量始于上下文包。核实真实情况，揭示相邻机制，核实外部前提，敲定文件系统布局，与用户逐项梳理，并在重新界定后消除虚假的争议。此技能中的大多数陷阱都源于派发前的失误。请将上下文包视为承重核心产物。

第五：**交付内容以决策为先，深入审查留档。**在编排器审查步骤中，撰写两份产物：brief.md（供用户阅读并作出判断，决策优先，约 1 页）和 <orchestrator>-review-deep.md（记录出处、内部讨论和诚实的自我评估）。用户必须只看简报就能作出判断——绝不要让他们为了弄清要决定什么而去翻阅深度审查。P26 为这种做法及其失败模式命名（需要高管风格简报时，却交付了全面的深度审查）。简报是衡量高度的标准：如果你无法将深度审查提炼成清晰、以决策为先的简报，就说明你的高度并没有自己以为的那么高。