docs: record the core self-evolution methodology - Reflection -> Fix-Skill -> Re-loop

User's key insight, recorded as a goal in the requirements doc (new §3.1): a failed node shouldn't just get a corrective retry (fix-bug, forgotten after this run) -- when the root cause is a systemic Skill defect, the Skill itself must be fixed (fix-skill, persists across all future tasks). Four-step chain: judgment fails -> Reflection-review node does full-chain root-cause diagnosis (one-off content error vs systemic skill defect) -> if systemic, a Fix-skill node calls the already-existing skill iteration machinery (skill_update.py::update_skill() + bug_record.py, real Git- versioned commits, previously only reachable via org_level_loop.py's coarse Org-level path, never from inside a Work Graph's own judgment/ loop_back cycle) -> loop back and re-run using the updated skill. Cross-referenced into the Phase 2 design doc: its dynamic_loop_back (§5) implements steps 1/2/4 of this chain but not step 3 (Fix-skill) -- flagged as the largest known scope gap in §8, not a missed detail. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

docs: record the core self-evolution methodology - Reflection -> Fix-Skill -> Re-loop
User's key insight, recorded as a goal in the requirements doc (new §3.1): a failed node shouldn't just get a corrective retry (fix-bug, forgotten after this run) -- when the root cause is a systemic Skill defect, the Skill itself must be fixed (fix-skill, persists across all future tasks). Four-step chain: judgment fails -> Reflection-review node does full-chain root-cause diagnosis (one-off content error vs systemic skill defect) -> if systemic, a Fix-skill node calls the already-existing skill iteration machinery (skill_update.py::update_skill() + bug_record.py, real Git- versioned commits, previously only reachable via org_level_loop.py's coarse Org-level path, never from inside a Work Graph's own judgment/ loop_back cycle) -> loop back and re-run using the updated skill. Cross-referenced into the Phase 2 design doc: its dynamic_loop_back (§5) implements steps 1/2/4 of this chain but not step 3 (Fix-skill) -- flagged as the largest known scope gap in §8, not a missed detail. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
bboonnee
1 parent ea19c7d2
Showing 2 changed files with 19 additions and 1 deletions
docs/todo/org-graph-unification-and-universal-self-planning-requirements.md
docs/todo/org-graph-unification-phase2-universal-self-planning-design.md
@@ -59,10 +59,25 @@
 | FR-1 | Org Graph 固定流程改为 `Planner → Validator(复核 Planner 产出) → Coder → Validator(终审实现)`：新增 `task.status` 枚举值（schema 迁移）+ `org_node_lifecycle._PRE_STATE`/`_POST_STATE` 扩展 + `run_task_lifecycle()`/`run_or_resume_task_lifecycle()` 新分支。**该分支落地时一并修复 `task-execution-resume-assumes-planner-artifacts-exist.md` 记录的 resume 假设 artifact 存在的 bug**（同一段代码路径，不分两次改）。 | 1 |
 | FR-2 | Coder（`implement_code()`）、Validator（`validate_implementation_with_own_graph()`）两处调用点，把硬编码 manifest 换成真实调用 `plan_work_graph(conn, "coder"/"validator", ...)`——函数本身已通用，只需替换调用点。 | 2 |
 | FR-3 | `graph_manifest` 节点 schema 扩展显式的"实现绑定"字段：这个节点由哪个 subagent + 哪个 skill + 哪些 tools + 输入输出 data 实现。今天的 `judgment`/`on_fail` 已覆盖"怎么判断成功/失败、失败去哪"，但"用什么实现"这一半目前只是 `_GENERIC_PROMPT_TEMPLATE` 给的一段自由文本 `task_prompt`，不是结构化字段——这是本次真正的新增 schema 工作。 | 2 |
-| FR-4 | 新增一个 org-agent-无关的"节点级验证"skill（可被任意角色的 `role.json` 引用），作为 `judgment.kind="llm"` 的标准实现：验证节点输出、判断根因、精确 `loop_back` 到需要修复的节点。用它统一/取代 `org_level_loop.py` 今天的粗粒度 `fast_lane`/`full_replan` 路由——这是 `org-graph-as-work-graph-unified-loop-requirements.md` 的核心诉求，按 §4 已拍板的方案 A（合图）落地：`loop_back` 目标节点和触发验证的节点在同一个 `work_graph_run` 内，不需要跨图寻址。 | 4 |
+| FR-4 | 新增一个 org-agent-无关的"节点级验证"skill（可被任意角色的 `role.json` 引用），作为 `judgment.kind="llm"` 的标准实现：验证节点输出、判断根因、精确 `loop_back` 到需要修复的节点，且当根因是**系统性 skill 缺陷**时先修 Skill 本身再重试——完整方法论见 §3.1，不是单纯"跳回某个节点重试"。用它统一/取代 `org_level_loop.py` 今天的粗粒度 `fast_lane`/`full_replan` 路由——这是 `org-graph-as-work-graph-unified-loop-requirements.md` 的核心诉求，按 §4 已拍板的方案 A（合图）落地：`loop_back` 目标节点和触发验证的节点在同一个 `work_graph_run` 内，不需要跨图寻址。 | 4 |
 | FR-5a | 前端新增 Org 级元图：把 Planner/复核 Validator/Coder/终审 Validator 四段渲染成一张顶层图，每段可展开成该 Org Agent 自己的 Work Graph 详情（复用现有 `renderGraphVisualizerPanel`，不重写渲染器）。 | 3 |
 | FR-5b | 前端新增同一个 `work_graph_run` 内按 `attempt_number` 的历史回放时间轴/scrubber，复用已经在拉取但未渲染的 `loop_back_events[].feedback`。 | 3 |
  
+### 3.1 核心方法论（用户 2026-08-08 拍板，作为本项目开发的目标写在这里）：失败即进化——Reflection → Fix-Skill → Re-loop
+
+**这是 Work Graph"自我进化"能力的精髓，FR-4 必须按这个方法论实现，不能退化成"判断失败→跳回某个节点重试"这么简单。** 用户原话的核心洞察：一个节点判断失败后，我们要的不只是"把这一次的错误修好"（fix-bug，只解决这一次），而是"让这一类错误以后不会再发生"（fix-skill，永久解决）——否则下一个类似任务撞上同一个坑，还是要重新踩一遍、重新修一遍。
+
+**四步链路**（不是一个笼统的"loop_back"，是四个明确的阶段/节点）：
+
+1. **判断分支**：节点产出被判定 `false`/`error`/`wrong`（`judgment.kind` 不管是 `mechanical` 还是 `llm`，只要 `ok=False`）——不是简单重试，跳转到分支 B。
+2. **分支 B 第一个节点：Reflection-review**——对整条链路做复盘，不只是"这个节点自己错在哪"，而是**全链路根因定位**：到底是哪一个更早的环节（可能是这个节点自己的 Skill 有缺陷，也可能是更早某个上游节点的产出本身就有问题）真正导致了这次失败。判断结论要落到两种性质里的一种：
+   - **一次性内容错误**（这次具体的产出恰好没写好，Skill/方法论本身没问题）——走现有的精确 `loop_back`（Phase 2 SDD §5 的 `dynamic_loop_back`）即可，跳回真正的根因节点重新生成。
+   - **系统性 skill 缺陷**（这个 org_node 用来产出这类内容的 Skill 本身有方法论层面的问题，同类任务会反复踩同一个坑）——进入第 3 步。
+3. **Fix-skill 节点**：不是修这一次的输出，是**修 Skill 本身**——真实调用已经存在的 Skill 迭代机制（`src/skill_update.py::update_skill()` + `src/bug_record.py::create_bug_record(root_cause_category='skill_defect')`），产出一次真实的、Git 版本化、可回滚的 Skill 内容更新（`skill_iteration` 表，`before_git_commit_sha`/`after_git_commit_sha` 都是真实 commit，不是模拟）。**这套机制在代码库里早就存在**（U-015/U-016 时期就建好了），但至今只在 `org_level_loop.py` 的 Org 级粗粒度路径上被触发过——FR-4 要把它真正接进 Work Graph 内部的判断/回路循环，让它成为节点级失败恢复的常规路径之一，不是只有跨 Org Agent 的大失败才配触发。
+4. **跳回执行**：Skill 更新落地后，跳回"用这个 Skill 的节点"重新执行——这次用的是刚修好的新 Skill，不是拿旧 Skill 再赌一次运气。跟 `_loop_history_prompt_suffix`（现有机制，把历史反馈拼进 prompt）的本质区别：prompt 里的反馈是**这一次任务专属、跑完就忘**的临时纠偏；Skill 更新是**持久化、跨任务复用**的真正修复——两者不互斥（可以同时生效：这次重试既带着历史反馈，也带着已经更新的 Skill），但 FR-4 的核心价值在后者。
+
+**跟 Phase 2 SDD 的关系**：`docs/todo/org-graph-unification-phase2-universal-self-planning-design.md` §5 设计的 `on_fail.action="dynamic_loop_back"` 是这个方法论第 1/2/4 步（判断失败 → 动态诊断根因节点 → 跳回执行）的**已完成设计**，但**第 3 步（Fix-skill）还没有设计**——目前的 `dynamic_loop_back` 只处理"一次性内容错误"这一种诊断结果，没有覆盖"系统性 skill 缺陷"这条分支。这是 Phase 2 设计文档需要补齐的部分，不是另开一个 Phase——具体设计（Reflection-review 节点判断"一次性 vs 系统性"的标准、Fix-skill 节点的 graph_manifest 形状、"用哪个 Skill 文件"跟"节点声明的 skill_ref"字段（FR-3）怎么对应上）留给该文档的下一次修订。
+
 ---
  
 ## 4. 关键架构决策：方案 A（合图）——已确认，2026-08-08
@@ -222,6 +222,8 @@ def _run_one_node(conn, run_id, org_node, skill_id, target_folder_path, node, ou
  
 ## 5. 憓 `on_fail.action = "dynamic_loop_back"`嚗笆摨 禮1.3嚗R-4 敹
  
+**2026-08-08 霂湔**嚗瘙﹝憓 禮3.1嚗"憭梯揖餈eflection  Fix-Skill  Re-loop"嚗 FR-4 瘜捏摰蛹郊憭梯揖eflection-review **憒蝟餌 Skill 蝻粹,耨 Skill 頨恬 `skill_update.py::update_skill()`,鈭批 Git  Skill 餈凋誨)**歲銵挽霈∠ `dynamic_loop_back` 閬洵 1/2/4 甇伐 + 頝喳銵笆摨"銝甈⊥批捆秤"餈蝘蝏**"蝟餌 skill 蝻粹"嚗洵 3 甇 Fix-skill 嚗瓷挽霈**嚗﹝撌脩撩嚗甈∩耨霈ｇ雿圾嚗eflection-review "銝甈⊥ vs 蝟餌"ix-skill  graph_manifest 敶Ｙskill_update.update_skill()` 閬 `skill_id`/`repo_path` 頝 禮4 蝥 `skill_ref` 摮挾笆摨
+
 ### 5.1 霂凋
  
 頝 `loop_back`嚗歲銝芾畾萄停香摰dynamic_loop_back` 銵函內"餈葵憭梯揖嚗銝甈∩靚嚗葵銝虜蟡迤霂亙"鈭**蝡舐恣批**嚗 Phase 1 撘恣 Validator 嚗葵餈葵韐萇
@@ -391,6 +393,7 @@ Phase 1 畾&quot;憭憭梯揖 `org_level_loop.py` 蝎漲頝舐
 2. **`promotes_to_artifact`嚗2.3嚗 Coder/Validator 摰"蝏漱隞ㄟ"餈蝥行** prompt 撅蔓蝥行,銝璇啣撩,捏銝 LLM 蝏葵憯唳 `promotes_to_artifact`嚗 artifact_type 蜀頨思雿,雿雿"餈漲憯唳"餈誑嚗,閬葉閫閬璇唳
 3. **`dynamic_loop_back` " source 餅活銝"嚗5.5 蝚 3 嚗閬 `work_graph_loop_limit_config` key 敶Ｙ**"{org_node}:{source_node_id}:total"` 餈葵雿撘瓷,摰閬餈 `settings_config.py` 霂/摰寡挾撘 key,餈閬撅
 4. **`org_level_loop.py` 瘚摮靘**嚗7.2 蝏偏嚗瓷捏,畾菔圾憸,銝﹝葵憸圾,Phase 2 銝瑪敶予撠曹"隞餃隞楝敺",摰憿箏砲
+5. **瘙﹝ 禮3.1 瘜捏洵 3 甇伐ix-skill嚗瘝⊥挽霈**嚗 禮5 撘憭游歇釣嚗dynamic_loop_back` 摰"霂 + 頝喳"嚗"蝟餌 Skill 蝻粹耨 Skill 頨"餈 FR-4 瘜捏＆閬﹝餈瓷蝏雿挽霈∠敶憭抒蝻箏嚗蝏憸遣霈桐蛹 Phase 2c嚗蝡 Phase 2d嚗挽霈∴摰銝剝摰
  
 ---