Reality-Driven Iteration

Do not optimize on explanations. Optimize only on evidence.

A behavioral SOP for AI agents that installs an Evidence-First cognitive circuit breaker into the execution loop. Prevents blind debugging, premature optimization, and explanation-driven development by enforcing a 7-step reality verification protocol.

Compatible with OpenCode / OhMyOpenAgent and any platform supporting Skills.

---

⚡ Why This Skill?

The Problem in Vanilla Agents	The RDI Way
Shotgun debugging — changing 10 things at once, not knowing which fixed it	One variable at a time — isolated iteration with mandatory mechanism explanation
Metric worship — "improve latency by 20%" without asking why	Target the reality goal — trace the metric back to the real-world objective it proxies
Explanation-driven optimization — "this sounds reasonable, let's try it"	Evidence Gate — three-tier lock: Observation → Hypothesis → Evidence
Provenance blindness — Dashboard shows A, Backtest shows B, database shows C	Provenance Before Optimization — confirm data source, time window, version, snapshot consistency before touching any parameter
Premature optimization — refactoring before understanding the root cause	Debug Pyramid — lock reality → measurement → causality → implementation → assumption, bottom-up
Over-optimization — never stop tuning, never let the system run stable	Freeze And Observe — when stable, stop. Let the system speak.
Cognitive debt — "it works, don't touch it"	Build Knowledge, Not Features — every iteration must yield permanent understanding

---

🧠 Core Philosophy: The 7-Step Loop

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

The skill installs a cognitive circuit breaker into the agent's execution loop:

1. Intercept — Detect trigger phrases (optimize, refactor, fix, debug, error, 性能优化, 调参数).
2. Halt — Pause any code-writing impulse.
3. Audit — Run the 7-step Evidence-First loop.
4. Evidence Gate — Only proceed if causality is verified, not just hypothesized.
5. Isolate — Modify one variable at a time.
6. Explain — If it works, say why it works, with evidence.
7. Log — Emit a structured iteration_summary capturing understanding gained, evidence level, and trap detected.
8. Freeze — When stable, enter observation phase. No more tuning.

---

🚀 Quick Start

Add this to your project's opencode.json:

{
  "skills": {
    "urls": [
      "https://raw.githubusercontent.com/liuhengyuan666/reality-driven-iteration/main/"
    ]
  }
}

OpenCode will automatically download and cache the Skill. No MCP server required — this is a pure behavioral SOP.

Local Install (Project-Level)

mkdir -p .opencode/skills/reality-driven-iteration
curl -o .opencode/skills/reality-driven-iteration/SKILL.md \
  https://raw.githubusercontent.com/liuhengyuan666/reality-driven-iteration/main/reality-driven-iteration/SKILL.md

Global Install

mkdir -p ~/.config/opencode/skills/reality-driven-iteration
curl -o ~/.config/opencode/skills/reality-driven-iteration/SKILL.md \
  https://raw.githubusercontent.com/liuhengyuan666/reality-driven-iteration/main/reality-driven-iteration/SKILL.md

---

🎯 Trigger Scenarios

The skill activates automatically when the user intent matches any of the following:

User says	Skill action
"Fix this bug / 为什么报错了"	Run Debug Pyramid from Reality layer downward
"Optimize / 优化一下 / 调参数"	Halt. Ask: what real-world goal does this optimize for? Enter Evidence Gate.
"Refactor / 重构"	Halt. Verify assumptions before touching code
"Vibe coding error"	Audit measurement & observation layers for false signals
"Performance tuning / 提高指标"	Challenge the metric. Check Provenance. Is it measuring the right thing?
"改权重 / 调阈值 / 新增因子"	Halt. Is there evidence the system needs this change?

---

🔧 The 7-Step Evidence-First Loop

When activated, the agent executes the loop in strict order:

1. Verify Reality

• Confirm the phenomenon actually exists (not a sampling artifact, not a cache issue, not a version mismatch).
• List [verified facts] vs [unverified assumptions] before any proposal.

2. Verify Measurement (Provenance Before Optimization)

• Are Dashboard, Backtest, Report, and database all pointing to the same data source?
• Are time windows, versions, and snapshots consistent?
• If conclusion is not traceable: stop optimizing. Fix provenance first.

3. Verify Causality (Evidence Gate)

• Three-tier lock:
  • Only Observation → allow hypothesis only, forbid optimization
  • Observation + Hypothesis → allow recording, forbid modification
  • Observation + Measurement + Evidence → allow isolated iteration
• The only valid reason to modify: new evidence proves the system has a problem.

4. Change One Thing

• One variable per iteration.
• Record expected result before change; compare after.
• If outcome diverges from expectation, re-enter Evidence Gate.

5. Build Knowledge

• What did we discover?
• What did we rule out?
• Which assumption was falsified?
• What knowledge can be permanently archived?
• If understanding didn't increase, the iteration is invalid.

6. Freeze And Observe

• When the system is stable, stop optimizing.
• Allowed during observation: monitoring, logging, audit, observability enhancement.
• Forbidden during observation: tuning parameters, weights, thresholds; adding new factors; changing core logic.
• Many real problems only surface after 30–90 days of stable operation.

7. Reopen Only With Evidence

• The only valid reason to restart development: new, verifiable failure evidence.
• Forbidden reasons: "it could be better", "the metric looks like it can go higher", "the market fits a narrative lately", "sounds reasonable".

---

🛡️ Optimization Trap Detection

The skill automatically detects and intercepts these traps:

Trap	Feature	Action
Explanation Trap	Changing because the explanation sounds reasonable	Stop. Demand evidence.
Metric Worship	Changing because we want the metric higher	Stop. Trace to the real-world goal.
Narrative Bias	Adjusting because the market fits a recent story	Stop. Narrative ≠ Evidence.
Recency Bias	Rushing to fix because the last run was bad	Stop. Check time window sufficiency.
Confirmation Bias	Only looking for data that supports the current hypothesis	Stop. Mandate counter-evidence search.
Premature Tuning	Tuning before the system is stable	Stop. Enter observation phase first.

---

📂 Repository Structure

reality-driven-iteration/
├── README.md                          # This file
├── LICENSE                            # MIT License
├── index.json                         # OpenCode skill discovery index
└── reality-driven-iteration/          # Skill directory
    └── SKILL.md                       # ⭐ Agent SOP — core behavioral contract

This is a lightweight, single-file skill. No runtime dependencies, no MCP server.

---

📜 License

MIT License — see LICENSE for details.