SKILL.md 10.3 KB

Edit Raw Blame History


planner.json 五节点裁剪判定表 v1

训练产出：workgraph-planning-methodology-trial（首训 v1）
自评分：100/100（digest/benchmark_v1.md，及格线65/目标线80，见 `evolvereport.md）
供system/agents/workgraph-planning/agent.md` Step 4 直接引用/粘贴。


〇、适用范围（先说清楚不管什么）
本表只回答一件事：宿主 org node 是 org-planner、骨架选定 planner.json 之后，
brd/prd/sdd/benchmark/validator 这五个节点里，哪个该裁、哪个该留、裁了下游 needs
怎么改。以下三件事不在本表范围，仍按 agent.md 原有逻辑处理：


骨架间选型（org-planner→planner.json / org-coder→executor.json /
org-validator→validator.json）——已经是 whenToUse 字段的确定性判据
（100% 由宿主类型决定，见 hunt/knowhow_v1.md 块C），不需要复杂度信号参与。
goal-benchmark/goal-test-data/goal-test-script 三选一或多选（27-E2E
§十一）——这是"验收方式用哪种载体"的选型决策，与本表的 benchmark 节点是否
保留是两个不同轴：本表只回答"要不要保留一个产 acceptance 的验收产出节点"，
不回答"该用打分式/数据驱动式/脚本式里的哪一种"。
图形状本身错了要不要重画——那是 agent.md Step4"重规划三选一"表格的
职责（remediation_note 触发），不是节点裁剪判据。


信号取值来源：S1-S5 的定义与判定方法完全复用 digest/complexity_signals_v1.md，
本文档不重新定义信号本身，只定义信号取值 → 节点裁/留 + needs 改法的映射。


一、决策流程（先过两道门，再逐节点判定）
输入：task-goal 原文 → 按 complexity_signals_v1.md 判定 S1(整数,关心1/≥2)、S2/S3/S4/S5(是/否)

G1（始终生效，不参与判断，只是提醒）
  五项校验（无环/单一入口/可达性/回退边标注/fail兜底边）与数据契约级联检查
  永远适用，不因任何信号组合而放松。

G2（S3 硬门）
  若 S3=是 → 全部 5 节点保留，不裁不并，直接终止决策，不再往下走。
  （地基级约束：数据持久化/多模块场景下，任务表面简单与否不影响架构决策，
   knowhow §A4 YAGNI张力 + complexity_signals_v1.md S3 段原文"无论其他信号
   如何组合"）

G3（S5 复用门，仅当 G2 未命中时判断）
  若 S5=是 且 能找到一份先例规划记录，且该先例记录明确标注了自己的 S1-S4
  取值，且四个信号值与本次任务逐一严格相同（缺一不算）
    → 直接复用先例的节点集合（含 needs 方案），跳过以下逐节点判定，终止决策。
  否则（S5=否；或 S5=是但找不到先例；或先例未标注S1-S4取值；或标注了但
  任一信号不一致）
    → 一律按 S5=否 处理，继续往下走逐节点判定。
  **fallback 说明**：本仓库当前全部历史规划记录（`hunt/knowhow_v1.md` 块C
  5份）都写于 S1-S5 信号体系引入之前，没有一份标注过信号取值——这意味着
  在 S1-S5 信号体系刚上线的阶段，G3 门实际上对所有历史先例都会走向"按S5=否
  处理"这个分支，这是符合预期的保守行为，不是判据失效；等新规划记录开始
  按本表标注信号取值后，G3 门才会真正触发复用。

若 G2、G3 均未命中，进入下面「二、逐节点判定表」（此时已知 S3=否）。


二、逐节点判定表（前提：S3=否，且 G3 未触发复用）
2.1 BRD（org-planner-brd）


S4
S1
S2
判定
理由


是
任意
任意
保留
BRD 的语义是"why"，存在价值在于向不同于 PRD 读者的第二方解释理由；S4=是 说明这个第二方真实存在，必要条件不满足，不裁


否
≥2
任意
保留
多个彼此独立可验收的交付物，各自的立项理由大概率不同，即便只面向单一读者也不满足"why 内容单一到能并入一段前言"的前提，从保守默认出发保留


否
1
是
裁剪
单一交付物 + 无第二方受众 + task-goal 原文已含可直接落地的验收清单/数值 → why 可以在 PRD 前言段一段话讲清，见 §四 裁剪连带修正清单


否
1
否
保留
虽满足 S1=1/S4=否，但 S2=否 说明连"做完什么算成功"都还没在原文讲清楚，此时更需要独立的 BRD/PRD 分别把 why 和验收标准想清楚，直接并入一段前言风险过高，保守保留


（以上 4 行覆盖 S1(1/≥2)×S2(是/否)×S4(是/否) 全部 8 种组合：S4=是 一行折叠
4 种；S4=否&S1≥2 一行折叠 2 种；S4=否&S1=1 按 S2 拆成 2 行；合计 4+2+1+1=8，
无遗漏组合。）
2.2 PRD（org-planner-prd）
任意信号组合下都不裁。

理由：org-planner-sdd 边 needs:["prd"]、org-planner-benchmark→validator
边 needs:["brd","prd","sdd"] 两条边都直接依赖 prd 这个 kind；裁掉它会让
两条边同时找不到产出方，触发 rule=data-contract 被引擎拒绝，且没有像
brd 那样"改成前言段"的补救办法——PRD 本身就是"what"的唯一来源，无处可并。
这是"地基级、不受任务复杂度影响"的约束（benchmark_v1.md D5 判据来源）。
2.3 SDD（org-planner-sdd）
节点本身不裁（结构原因见下），内容深度随 S1 二值调整：


S1
内容深度
理由


1
精简
单一交付物、已知 S3=否（无跨模块整合点），SDD 可以只写最小必要的技术决策，不需要展开"多交付物间如何整合"这类内容


≥2
完整
多个独立可验收交付物之间的技术整合点必须单独展开，不能省略


为什么不是"裁剪"而是"精简"：org-planner-benchmark 边
produces:["sdd"] 是这条边存在的前提。真要把 SDD 从图上整个删掉，必须把
prd→sdd→benchmark 改造成 prd→benchmark 直接产出 prd/跳过 sdd
kind——这已经是图形状变更，不是"裁剪骨架内某个节点"，超出本表定义的
裁剪范围，按 §〇 第3点交给"图形状是否错了"那层判断，不在本表处理。
2.4 benchmark（org-planner-benchmark）
任意信号组合下都不裁。

理由：这是本图内 acceptance kind 的唯一生产者；节点带 writesArtifacts:true，
产物写进 root run 的 artifacts/ 共享区，消费方不止本图内的 validator 节点，
还包括另一张图——同一 task 下游、由 org-validator 宿主的 validator.json
图，靠这份 acceptance 产物判定整个任务是否达标。裁掉它的影响是跨图断供，
比裁 brd/sdd 更不可逆。S2 信号只影响它的工作量（S2=是 时从"设计验收维度"
降为"格式转译"），不影响它是否存在——工作量变化留给 goal-benchmark 本体
自己的提示词处理，不是本表的裁剪判据。
2.5 validator（org-planner-validator）
任意信号组合下都不裁。

理由：这是四张骨架共有的"做→自检→本层验收"形状（work-graph-templates/
README.md L29）里"自检"这一步——检查 brd/prd/sdd 三份文档内部是否矛盾。
裁掉它等于让 planner 输出的文档不经内部一致性检查就流向下游 org-validator，
把本该在本图内发现的矛盾转嫁给下一张图。needs 随 brd/prd/sdd 实际留存情况
自动调整，不是独立判断（见 §四）。


三、汇总（速查）


节点
可裁剪？
触发条件


brd
是，有条件
S3=否 且 S5未命中复用 且 S4=否 且 S1=1 且 S2=是


prd
否
地基级，sdd/benchmark→validator 两条边直接依赖


sdd
否（内容可精简）
精简条件：S3=否 且 S1=1；节点本身裁剪需图形状变更，超出本表范围


benchmark
否
地基级，跨图（validator.json）依赖它的 acceptance 产物；选型层面的增删属于27-E2E§11，不在本表


validator
否
地基级，四骨架共有的"自检"步骤


全公司当前唯一可能触发裁剪的分支就是 brd，其余四个节点在 S1-S5 信号体系下
永不裁剪——这不是偷懒简化，是 §2.2/§2.4/§2.5 分别给出的三条独立地基级理由
（数据契约直接依赖 / 跨图断供 / 骨架共有自检步骤），三者互不依赖，任何一条
单独成立就足以否决对应节点的裁剪。


四、裁剪 brd 的连带结构修正清单（触发 §2.1 裁剪行时，全部执行）

needs 调整：org-planner-benchmark --success--> org-planner-validator
边的 needs 从 ["brd", "prd", "sdd"] 改为
[{"kind": "brd", "required": false}, "prd", "sdd"]（brd 变可选输入，
不阻断这条边）。
删除失效的 backward 边：org-planner-prd --fail--> org-planner-brd
（edgeKind: backward）这条边的目标节点已不存在，必须删除，不能留着
（留着会让边引用一个不存在的节点，图无法落地）。
确认新入口：org-planner-prd 的 forward 入度归零，自动成为新的
唯一入口节点。按约束五例外条款，入口节点不需要为自己另配 fail
兜底边——prd 不用因为"看起来没有兜底边"而被误判为不合法，也不应该
为了凑一条兜底边而画蛇添足新增一条。
收尾复核：重新过一遍五项校验手工验算法第 2/3/4/5 条（第1条无环性
不受影响，删边不改变既有节点间的拓扑序）。完整过一遍示例见
sample_verification.md 中 C4 案例的验算表。


五、"why 内容并入 PRD 前言段"的落地方式（brd 裁剪时的内容处理）
裁掉 org-planner-brd 节点后，org-planner-prd 的产出物必须在文档开头新增
一段"背景/为什么做这件事"的前言段，覆盖原本该由 BRD 承担的 why 内容——这不是
可选的润色，是 §2.1 裁剪判据成立的前提条件本身（S2=是 意味着"what"已经清楚，
但"why"仍然需要落地到某处，只是从独立节点降级为前言段，不是被删除）。若下游
org-planner-validator 在自检阶段发现 PRD 前言段对 why 的交代不充分，允许
在 remediation_note 里要求下一轮重新引入独立 brd 节点（走 agent.md
Step4"重规划三选一"里"图形状本身错了"那一行）。