yyyyyhhhhh0639 变更决策框架 (Change Decision Framework)
决定"渐进修改"还是"推倒重建"（代码/文档/技能/配置），以及如何突破自指螺旋和完美主义循环。
When to Use
- 面对一个需要修改的对象（skill、文档、代码库、配置），犹豫"打补丁还是重写"
- 用户说"这个有价值/以后能用/该沉淀"——触发知识落盘决策（配合
session-knowledge-capture） - 讨论方法论/元认知话题，需要把讨论操作化为可执行规则
- 审查发现目标物有多处问题（过时/矛盾/缺失），决定修复策略
Don't use for:
- 任务计划编写 →
plan - 计划审查（CEO/工程双模式）→
plan-review - 知识是否值得落盘的价值判据 →
memory-storage-management+session-knowledge-capture
一、成本是四维向量，不是标量
"哪个成本更高"是伪问题——成本由四个独立维度组成，不同场景权重不同：
| 维度 | 渐进修改（patch） | 推倒重建 |
|---|---|---|
| 当前修复时间 | 低（定点 patch） | 高（全量重写） |
| 信息损失风险 | 低（历史保留，可标注） | 高（除非备份，否则历史永久丢失） |
| 验证/回滚成本 | 低（每处独立验证） | 高（整体验证，回滚即全丢） |
| 长期技术债 | ⚠️ 高（补丁式演进→新旧并存） | 低（若设计正确，结构统一） |
两个反直觉：
- "从头"是假象——重建者带着全部领域知识，不是从零开始；被脑中知识掩盖的成本仍然存在
- "小改"的低成本也是假象——每次 patch 留下的技术债（新旧并存、标注段、兼容层）在第 N 次修改时集中爆发。一个对象因多次 patch 积累的过时信息，就是过去"低成本的渐进修改"的账单
二、三问判断准则（操作化核心）
判断时依次问三个问题，任一命中"重建"即重建：
| # | 问题 | 渐进修改的条件 | 重建的条件 |
|---|---|---|---|
| 1 | 框架本身要不要保留？ | 章节/层次/边界合理 | 结构混乱、内容交错无法分离 |
| 2 | 过时内容有没有信息价值？ | 可标注保留（历史配置/旧版本细节） | 纯垃圾占多数、保留价值低 |
| 3 | 改完能不能保持可验证？ | 每处 patch 可独立验证 | 只能整体验证 → 重建更安全 |
修改比例经验值：<30% 内容需改 → patch；>50% → 重建；30-50% → 看结构健康度。
实例（2026-08-07 SKILL v2.0.0）：15 项问题（9 过时/3 矛盾/3 缺失），但结构健康（8 章框架合理）+ 历史信息有价值（1.7.1 细节可标注）+ 修改比例 ~30% → 8 处 patch 而非重写。代价是文档保留"历史配置/1.7.1 时代"标注段（渐进的税）。
三、突破自指/交叉螺旋
改进 A 时调用不完善的 B，用 B 的标准完善 A，A 又被 B 引用——循环依赖。三条突破方法（按优先级）：
1. DAG 分层（根本解）
知识体系按依赖方向排成有向无环图，下层永不依赖上层：
L0 事实层：源码、官方文档、实测输出 ← 不可约减，不依赖任何规范
L1 方法论层：价值判据、触发理论、本框架 ← 只依赖 L0
L2 应用层：具体 skill/文档/代码 ← 依赖 L1+L0
核心规则：改进 L2 时引用 L1 或直接 L0（源码实证）；禁止 L2 之间互相引用作为标准。
2. 外部锚点（破环）
自指螺旋本质是用不完备自证（系统无法用自身证明自身）。破法：引入外部参照——
- 改记忆规范 → 引用源码事实（如
_char_limit()行为），不引用"上次怎么说的" - 改技能规范 → 引用结构要求（frontmatter 校验），不引用"别的技能也这么做"
- 不确定 → 查官方文档/源码（L0），永远有路可退
3. 改进记录标注"本次所用标准"
每次交叉引用显式记录"本次用了 X 作为标准，Y 未验证"。不解决螺旋，但把债务显式化——显式债务可审计可还，隐式债务会腐烂。
四、先做后改 vs 想好再做：伪二选一
两者缺的是同一个东西：边界条件。
| 先做后改 | 想好再做 | |
|---|---|---|
| 缺陷 | 误差/债务累积 | 完美主义循环 |
| 缺什么 | 完成标准（DoD：做到什么程度停） | 时间盒（timebox：想到什么程度必须动手） |
| 突破 | 验收标准 + 回滚点（.bak + git） | 到点必须动手，允许"够好"而非"完美" |
合并策略：想（受限）→ 做（受限）→ 验（强制）→ 循环。债务累积不是"先做"的必然结果，是"做而不验"的结果；完美主义不是"想"的必然结果，是"想而无界"的结果。
按回滚成本分流：
- 数据/外部影响（改配置、删文件）→ 先想后做（高回滚成本）
- 知识/文档/技能 → 先做后改（git + .bak 兜底，回滚成本≈0）
- 记忆/身份文档 → 走审批流程（强制 diff 审阅）
Common Pitfalls
- 改源码前先查官方扩展机制（2026-08-07 实证）——修改有文档系统的工具（Hermes、CLI、框架）前，先查官方文档/源码是否有扩展点（config 键、插件、hook、CLI 子命令），再决定是否源码补丁。本例：危险命令防护先打了 approval.py 源码补丁（DANGEROUS_PATTERNS +3 正则），后查官方文档发现 Shell Hooks（
hooks.pre_tool_call）是官方指定拦截点，且 hooks.md 明确pre_approval_request是 observer-only 不能 veto——源码补丁是最后手段（升级被覆盖、偏离官方设计）。查证方法：官方 docs 全文 grep（hooks.md/desktop.md/plugins.md）+ 本地源码调用点确认（register_from_config只在 cli.py 和 gateway/run.py 调用）。 - 单会话视角判断落盘价值——"诊断已在会话知识中"≠"无需落盘"：会话知识是被动查询（session_search），记忆是每轮注入。防再发类诊断必须放每轮可见位置（2026-08-07 实证：session-knowledge-capture 技能建好但从未触发，因为没有记忆锚点）
- 技能存在 ≠ 会被触发——只有索引层（描述触发词）的规范不可靠；必须补注入层（记忆锚点）或流程层（确定性命令）。四层触发保障：索引层 < 注入层 < 流程层（references 为档案层）。源码事实（2026-08-07）：skill 描述在 system prompt 索引中截断到 60 字符（
skill_utils.py:849 SKILL_PROMPT_DESC_LIMIT=60, desc[:57]+"..."），触发词必须落前 57 字符；记忆全文注入无截断（memory_tool.py:737），可写无条件指令 - "这个有价值" 停留在讨论——用户表达"有价值/该沉淀/以后能用"是执行信号，不是讨论话题；立即进入收割流程（session-knowledge-capture），产出 dry-run 提案或落盘
- 被"完美框架"困住——方法论讨论很容易无限细化；设置轮次上限（最多想 N 轮），到点用三问+DoD 落地
Verification Checklist
- 决策前明确问了三个判断问题（框架/信息价值/可验证）
- 若选渐进：每处 patch 有独立验证 + 回滚点（.bak/git）
- 若选重建：已确认信息损失可接受（备份或低价值）
- 引用规范时标注了层级（L0 事实 / L1 方法论 / L2 应用）
- "有价值"信号触发了落盘动作（dry-run 或执行），未停留在讨论