reality-driven-iteration - SKILL.md Agent Skill

name: reality-driven-iteration description: | 当软件工程、项目开发、代码Debug陷入异常，或用户盲目要求“优化/重构”某个功能，亦或在Vibe Coding中遭遇未知错误时自动触发。该技能引导Agent建立 Evidence-First 的认知框架，阻止基于解释而非证据的无效优化。WHEN: "debug", "optimize", "refactor", "fix this", "性能优化", "代码重构", "为什么报错了", "运行失败", "vibe coding error", "调参数", "改权重", "提高指标". ACTIVATES: Verify Reality → Verify Measurement → Verify Causality → Change One Thing → Build Knowledge → Freeze And Observe. license: MIT compatibility: opencode metadata: version: "2.0.0" author: "Lhy" tags: "debugging, optimization-guard, cognitive-sop, agent-behavior, workflow, reality-check, evidence-first, vibe-coding"

Reality-Driven Iteration — Evidence-First Cognitive Guard

Motto: Do not optimize on explanations. Optimize only on evidence.

不要因为解释听起来合理而优化，只因为证据证明需要优化才优化。

0. 核心信条

第一原则：Evidence Before Change。 没有证据，不修改代码。

第二原则：Provenance Before Optimization。 优化任何指标前，先确认数据来源可信。

第三原则：Build Knowledge, Not Features。 每次迭代必须增加对系统的理解，而不仅仅是改变代码。

当执行本技能时，Agent 必须立即暂停任何"直接编写解决方案/优化代码"的冲动。先执行认知审计，再行动。

1. Evidence-First 执行框架（The 7-Step Loop）

面对任何系统异常、优化需求或重构请求，Agent 必须按以下顺序执行，不可跳过。

Verify Reality          ← 现象真实存在吗？
    ↓
Verify Measurement      ← 测量可信吗？数据来源一致吗？
    ↓
Verify Causality        ← 原因被证实了吗？还是只是假设？
    ↓ [Evidence Gate]
Change One Thing        ← 一次只修改一个变量
    ↓
Build Knowledge         ← 记录新理解、排除的假设、沉淀的知识
    ↓
Freeze And Observe      ← 停止优化，进入观察期
    ↓
Reopen Only With Evidence ← 只有新证据才能重新进入开发

2. Verify Reality — 确认现象真实存在

目标：区分"真实问题"与"观测假象"。

行动：检查配置、接口、状态机。代码真的实现了设计吗？我们认为的运行规律是真的吗？
输出约束：在给出任何修改建议前，先列出 [已证实的客观事实] 与 [未经证实的假设]。
禁止：在假设未被验证前提出优化方案。

典型陷阱：

指标在特定时间窗口看起来不好，但换一个窗口就正常。
单次异常被当作系统性问题。
本地环境与生产环境表现不一致，却基于本地观测做优化。

3. Verify Measurement — 确认测量可信

目标：确保数字可信，且所有相关数字来自同一现实。

Provenance Before Optimization

在优化任何指标前，Agent 必须先确认以下一致性：

数据来源一致：Dashboard、Backtest、Report、数据库中的数字是否指向同一数据源？
时间窗口一致：不同系统的观测时间是否对齐？
版本一致：代码版本、数据版本、配置版本是否一致？
快照一致：如果存在缓存/快照，是否已过期？

如果结论无法追溯：停止优化。先解决溯源问题。

典型陷阱：

Dashboard 显示 A，Backtest 显示 B，Report 显示 C，然后开始调参数——却不知道哪个是真的。
指标计算口径在不同模块中不一致。

4. Verify Causality — Evidence Gate（证据门）

目标：确保"原因"被证实，而非仅仅"解释起来合理"。

这是最重要的拦截层。任何优化建议在实施前必须满足：

□ 现象被观察到（Verify Reality）
□ 测量可信（Verify Measurement）
□ 原因被验证（Evidence Gate）
□ 修改路径被验证（Change One Thing）

分级拦截策略：

满足条件	允许行动
只有现象（Observation）	仅允许提出假设，禁止优化
现象 + 假设（Hypothesis）	允许记录，禁止修改
现象 + 测量 + 证据（Evidence）	允许执行隔离迭代

典型陷阱：

解释听起来合理（如"risk权重过高"），但缺乏证据支撑。
因为"希望指标更高"而优化。
因为"市场最近表现符合某个故事"而调整参数。

🚫 禁止修改的唯一原因只能是：新的证据证明系统存在问题。

5. Change One Thing — 隔离迭代

目标：建立因果，而非相关。

规则：一次只能修改一个变量。
机制解释：修改后如果有效，必须说出"为什么有效"的深层机制。禁止回答"不知道为什么，但现在能跑了"。
审计要求：修改前记录预期结果；修改后对比实际结果与预期。如果偏差超过预期，必须重新进入 Evidence Gate。

6. Build Knowledge — 知识积累

目标：让每次迭代成为永久资产，而不仅仅是临时修复。

每次迭代结束，Agent 必须回答：

我们发现了什么？ —— 新的客观事实
我们排除了什么？ —— 被证伪的假设
哪个假设被证伪？ —— 明确记录，防止未来重复踩坑
哪个知识可以永久沉淀？ —— 可复用的系统理解

💡 如果无法增加理解，则本次迭代无效。

7. Freeze And Observe — 观察期

目标：防止过度优化，让系统在稳定状态下运行足够长的时间以暴露真实问题。

进入观察期的条件

当系统同时满足：

测量可信（Provenance 清晰）
逻辑一致（无已知矛盾）
关键 Bug 已修复（Critical issues resolved）

Agent 必须建议进入观察期。

观察期规则

允许：

监控（Monitoring）
日志（Logging）
审计（Audit）
可观测性增强（Observability improvement）

禁止：

调参数
调权重
调阈值
新增因子
修改核心逻辑

除非出现明确失效证据。

观察期不是停顿，而是让系统"说话"。很多真正的问题在稳定运行 30-90 天后才会暴露。

8. Reopen Only With Evidence — 只有新证据才能重启开发

目标：防止解释驱动的反复修改。

从观察期重新进入开发迭代的唯一条件：

出现新的、可验证的失效证据
或观测到系统行为与现有理解不一致

禁止以下原因重新启动开发：

"我觉得还可以更好"
"这个指标看起来能再高一点"
"最近市场表现符合某个理论，我们应该调整"
"解释起来合理"

9. Optimization Trap Detection（优化陷阱检测）

Agent 必须识别并拦截以下典型的"解释驱动开发"陷阱：

陷阱	特征	处理方式
Explanation Trap	因为解释听起来合理而修改	停止。要求证据。
Metric Worship	因为希望指标更高而修改	停止。追问指标背后的现实目标。
Narrative Bias	因为市场最近符合某个故事而调整	停止。叙事不等于证据。
Recency Bias	因为最近结果不好而急于修复	停止。检查时间窗口是否足够。
Confirmation Bias	只寻找支持当前假设的数据	停止。强制寻找反证。
Premature Tuning	在系统未稳定时就开始调参数	停止。先进入观察期。

10. Debug Pyramid 逆向排查法（底层执行手册）

当系统出现具体 Bug 或异常时，在完成第1-4节（Verify Reality → Verify Measurement → Verify Causality → Change One Thing）的认知审计后，进入以下 Debug Pyramid 逐层执行排查。Pyramid 三层分别对应第2节（现实检查）、第3节（测量检查）、第5节（隔离修改）的落地执行细节。

步骤 1：验证假设与实现（Assumption & Implementation Check）

检查配置、接口、状态机。代码真的实现了设计吗？
列出 [已证实的客观事实] 与 [未经证实的假设]

步骤 2：校验测量与观测（Measurement & Observation Check）

排查数据样本偏差、时间窗口偏差、幸存者偏差
追问：指标真的在测量目标吗？

步骤 3：锁定机制并执行隔离迭代（Isolate & Explain）

一次只修改一个变量
解释"为什么有效"的深层机制

优先修复级：认知错误 > 测量错误 > 实现错误 > 参数错误

💡 警告：若发现团队在参数层花费了 80% 的时间，Agent 必须提醒用户回归 Verify Reality 和 Verify Measurement 层。

11. 结构化输出约束 (Observability Log)

每一轮迭代结束或修复完成后，Agent 必须在回复末尾附带以下结构化认知日志：

{
  "iteration_summary": {
    "code_changes": "+X -Y lines",
    "understanding_gained": "本次迭代获得的关于系统现实的新理解（严禁为0）",
    "evidence_level": "Observation/Hypothesis/Evidence/Verified",
    "trap_detected": "无 / Explanation Trap / Metric Worship / ...",
    "phase_recommendation": "Continue / Observe / Stop"
  }
}

12. 退出开发条件 (Exit Rule)

当且仅当满足以下全部条件时，Agent 必须提示停止开发，进入观察阶段：

现象背后的一致性问题已被完全理解；
修复的深层机制已被合理解释；
测量指标已被证实可信；
系统表现已稳定；
最近一次迭代带来的理解增量已记录并沉淀。

13. 异常降级策略 (Fallback)

如果用户由于紧急线上故障等原因，强行要求跳过本 Skill 的认知审计（例如输入 force patch），Agent 可降级为直接修复模式，但必须在修复代码上方标注：// WARNING: Unverified optimization. Cognitive Debt Added.
降级后，Agent 仍应在后续会话中补全 Evidence Gate 审计和知识沉淀。

14. Success Criteria

一个合规的会话应包含：

Verify Reality — 至少确认了一个真实存在的现象；
Verify Measurement — 确认了数据来源和口径的一致性；
Evidence Gate — 任何修改都有证据支撑；
Change One Thing — 每次修改一个变量；
Build Knowledge — 记录了理解增量；
Freeze And Observe — 在系统稳定时建议观察期。

如果会话结束时，以上条目在相关场景下未被调用，视为认知债务（Cognitive Debt）已产生。建议补全审计。