Bug Fix v4.0 — OpenClaw Edition (Zero-Regression + Portable)

Core Promise: Fix completely. Fix everywhere. Break nothing. Learn from every fix.

---

Iron Rules (12 — NEVER Violate)

CODEBLOCK0

---

Workflow Overview

CODEBLOCK1

---

Phase 0: Triage + Severity

Classify severity AND tier FIRST to control workflow depth.

Severity Classification (controls workflow depth)

Severity	Criteria	Workflow	Time-box
P0 Critical	Production down / data loss / security	FULL (all phases)	4h escalation
P1 High

Core feature broken / data corruption | FULL (all phases) | 8h escalation | | P2 Medium | Non-core feature / UI issue | STANDARD (skip 3C) | 16h | | P3 Low | Cosmetic / minor edge case | QUICK (skip 2C, 2D, 3A-3C) | No limit |

Tier Classification (controls fix path)

Tier	Criteria	Path
Trivial	Typo, config value, 1-line obvious fix, no behavioral change	Quick Fix (below)
Standard

Logic bug, 1-3 files, clear symptom, no cross-module risk | Standard Path (skip phases marked "Complex only") | | Complex | Cross-module, >3 files, shared utility, schema change, multi-process | Full Path (all phases mandatory) |

Quick Fix Path (Trivial only)

CODEBLOCK2

After quick fix: update references/bug-records.md, done. No RCA, no impact chain, no self-reflection needed.

If "trivial" fix touches >1 file or changes behavior → upgrade to Standard.

Auto-Initialize Knowledge Files

CODEBLOCK3

---

Phase 1: Reproduce

MUST have evidence before continuing. No evidence = no fix.

Bug Type	Evidence Required
Backend error	Stack trace + request/response
Frontend UI

Screenshot + browser console + user repro steps (Rule 8) | | Performance | Before/after metrics + profiler output | | Intermittent | Timing conditions + frequency estimate |

UI Bug Protocol (Rule 8):

1. 1. Get user screenshot or screen recording
2. Open browser DevTools → check Console for errors/warnings
3. Inspect DOM structure (check for overflow clipping, z-index, Portal needs)
4. Reproduce the exact user steps
5. ONLY THEN form hypotheses

Evidence Bundle Template

CODEBLOCK4

---

Phase 2: Root Cause Analysis

2A: Hypothesis Ladder

#	Hypothesis	Likelihood	Confirmation Test	Rejection Test	Status
1	[description]	High/Med/Low	[prove it IS this]	[prove it is NOT this]	[ ]

Rules: Sort by likelihood → each must be falsifiable → run rejection tests first → test ONE at a time → use 5 Whys to reach root cause.

Root Cause Confirmation Gate (Rule 1)

Root cause is confirmed only when ALL 4 conditions are met:

Gate	Meaning
Reproducible	Can trigger symptom in controlled scenario
Causal

Minimal change makes bug disappear |
| Reversible | Reverting the change makes bug reappear |
| Mechanistic | Can point to exact code path / state transition |

Framework Assumption Audit (Rule 7)

When fix involves framework/library behavior: list assumptions → read source code to verify → document in comments with source references.

2B: Search Knowledge Files (Rule 12)

Search bug-patterns.md and bug-records.md for matching patterns.
Skip if files don't exist (see Phase 0 auto-init).

Match Level	Action
High (symptom + root cause match)	Apply known fix, can skip remaining RCA
Medium (similar symptom)

Reference strategy, verify | | No match | Full investigation, must deposit after fix |

2C: Impact Chain (Rule 3)

Dimension	What to Check
Code	Bug file → direct callers → indirect callers → deep callers
Data

Corrupted records in DB/file/cache? Repair script needed? | | Time | When introduced? Duration of exposure? Users affected? | | Event | Message queues, WebSocket, background workers affected? |

2D: Similar Issue Scan (Rule 3)

Scan ALL files for the same bug pattern, not just the reported file.

CODEBLOCK5

---

Phase 3: Scope + Prediction

Scope Accuracy Gate (Rule 2)

#	Gate	Meaning
1	Consumer List	All consumers (callers/dependents) enumerated
2

Contract List | Modified contracts/interfaces/behaviors listed | | 3 | Invariant Check | Must-hold invariants listed | | 4 | Call Site Enum | All call sites enumerated and classified | | 5 | Duplicate Scan | No parallel implementation left unfixed |

3A: Side Effect Prediction (Rule 4)

1. 1. Change Blueprint — What exactly will change
2. Impact Ripple — L0 (code) → L1 (module) → L2 (feature) → L3 (system) → L4 (user)
3. Blind Spot Check — Read references/blind-spots.md and execute every active check
4. Go/No-Go Decision

Quick version (for Standard-tier, ≤5 LOC, 1 file):
CODEBLOCK6

3B: Fix Strategy Comparison (>10 LOC, Complex only)

Dimension	Strategy A	Strategy B
LOC change
Impact scope

| | | Regression risk | | | | Rollback-able | | |

---

Phase 4: Fix

• - Minimal change, prefer ≤50 LOC; justify if more
• ONE change at a time, never batch unrelated fixes
• Layer Rule (Rule 10): Before writing fix code, verify you're fixing the right layer:

Problem in…	Fix…	Do NOT fix…
Params/config	Config or param passing	Business logic
Single component

That component | Framework | | Multiple components same issue | Framework/base class | Each component one by one | | Docs vs code mismatch | Both sides in sync | Only one side |

• - Pattern matching safety (Rule 11): regex, string match, name lookup → always consider boundary conditions
• DB schema change? Generate Alembic migration:

  cd backend && alembic revision --autogenerate -m "describe change"
  

---

Phase 5: Verify + Review

5A: Regression Verification (Rule 5)

Category	Checks
Functional	Unit tests + integration + API + E2E + manual
Performance

No N+1 queries, no resource leaks, no response time increase | | Concurrency | Thread-safe shared state, atomic operations, no race conditions |

Test the entire impact chain (L0-L3), not just the original bug.

5B: Runtime Deployment Verification (Rule 6)

Step	Action	Evidence
1	Clear Python bytecode cache	INLINECODE2 removed
2

Restart backend service | PID changed from X to Y | | 3 | Health check passes | /docs returns 200 | | 4 | Exercise the fixed code path | Request triggers fixed logic |

If NOT deployed → restart and re-verify before proceeding.

5C: Bug Summary + Code Review (Rule 9)

CODEBLOCK8

Output Bug Summary → run code-review skill → if review finds issues → fix → re-verify

Stop condition: Code review clean + regression passed + deployment verified + original bug fixed.

Special Checks

Bug Type	Key Checks
API Bug	Frontend → API → Schema → Service → DB chain; field completeness
DB Migration

Model changed → alembic revision --autogenerate; no migration = schema drift | | System-level | Draw E2E chain; define handshake evidence per edge; insert probes first | | Cross-Surface | Shared artifact → identify contract → consumer list → regression matrix |

---

Phase 6: Knowledge Deposit + Self-Reflection

6.1 Update Knowledge Files (Rule 9)

File	When to Update
INLINECODE6	Every fix (project history)
INLINECODE7

New pattern / new fix strategy (universal) | | references/blind-spots.md | New blind spot discovered |

6.2 Self-Reflection (Rule 9)

Dimension	Score (1-5)	Evidence
First-time correctness	[1-5]	Did the fix work on first attempt?
Scope accuracy

[1-5] | Did I find all affected areas? | | Minimal change | [1-5] | Was the change as small as possible? | | Side effect prediction | [1-5] | Did I predict all side effects? | | Root cause depth | [1-5] | Did I fix root cause, not symptom? | | Total | [/25] | |

| Issue | What Happened | Why I Missed It | Prevention |
|-------|--------------|-----------------|------------|

Regression Autopsy (when fix introduced a regression)

CODEBLOCK9

---

Domain-Specific Checks

Bug Type	Key Checks
Backend/API	Schema drift, timeout/retry, transactions, N+1, connection pool, ORM lazy loading
Frontend/UI

State (useEffect deps, unmount), race conditions, CORS, hydration, overflow/Portal |
| System-level | Cross-layer chain, async/streaming, IPC, routing |
| Framework | Read source code first (Rule 7), verify assumptions with tests |
| AI/LLM | Tool binding modes, simulated vs native, streaming, token limits |

---

Skill Delegation

Trigger	Delegate To
Need new API endpoint	fullstack-developer
UI fix needed

frontend-design |
| Schema change needed | database-migrations |
| After fix (mandatory) | code-review |

---

Anti-Patterns (FORBIDDEN)

Forbidden	Correct
Fix without RCA	Hypothesis ladder first
Single hypothesis then fix

List 3-5 hypotheses, verify each |
| Fix UI bug by code reading alone | Get runtime evidence first (Rule 8) |
| Skip consumer list for shared code | Fill consumer list first |
| Tests pass but server runs old code | Clear cache + restart + verify fix is live (Rule 6) |
| Fix code but ignore corrupted data | Assess data impact + repair if needed |
| Trust framework docs blindly | Read source code or run tests (Rule 7) |
| Fix one copy, miss the duplicate | Grep function name; check both Path A and Path B |
| Pattern match without boundary check | Add word boundaries / anchors / exact match (Rule 11) |
| Model changed but no migration | Run alembic revision --autogenerate |
| Use full workflow for a typo | Use Quick Fix path (Phase 0 Trivial tier) |
| Skip self-reflection | Must score, analyze, and learn |

---

Final Checklist

Core (Standard + Complex tiers)

#	Check	Phase
1	Severity (P0-P3) + Tier (Trivial/Standard/Complex) classified	0
2

Root cause passes 4 gates | 2A | | 3 | Bug pattern library + records searched | 2B | | 4 | Impact chain traced (code+data+time+event) | 2C | | 5 | Similar issue scan completed | 2D | | 6 | Scope passes 5 gates (incl. duplicate scan) | 3A | | 7 | Side effect prediction + blind spot check | 3A | | 8 | Regression verification ALL passed (L0-L3) | 5A | | 9 | Runtime deployment verified | 5B | | 10 | Bug Summary output + code-review passed | 5C | | 11 | Knowledge files updated | 6.1 | | 12 | Self-reflection completed | 6.2 | | 13 | If DB model changed: Alembic migration generated | 5 | | 14 | User confirmed fix + no new bugs | Final |

Trivial Tier Checklist (Quick Fix path only)

#	Check	Status
1	Fix applied and tested (lint/test/manual)	[ ]
2

Bug record entry added | [ ] | | 3 | No behavioral change introduced | [ ] |

---

OpenClaw Project Context

Architecture Map

CODEBLOCK10

Tech Stack

Layer	Technology
Backend	FastAPI + Python 3.11+
ORM

SQLAlchemy 2.0 (async) | | DB | PostgreSQL (asyncpg) or MySQL (aiomysql) | | Migrations | Alembic (backend/alembic/) | | Cache | Redis | | AI | LangChain 0.3.x + LangGraph 0.4.x | | Vector DB | ChromaDB | | Frontend | React 18 + Vite + TypeScript | | UI | Radix UI + Tailwind CSS | | State | Zustand + TanStack Query | | Tests | pytest (backend), Vitest (frontend) | | Deploy | Docker Compose, supports PyInstaller desktop build |

High-Risk Bug Zones

Backend Hot Zones

Zone	Files	Why It's High-Risk
Simulated Tool Call Parsing	INLINECODE11, INLINECODE12	Regex-based; dual implementations; multi-arg edge cases
Agent Executor

services/agent_executor.py | 3000+ LOC; native + simulated modes; complex streaming | | Tool Argument Remapping | core/graph/nodes/tool_node.py | LLM wrong param names → alphabetical guess | | LLM Streaming (httpx) | services/llm_manager.py | Reasoning model fallback; SSE; reasoning_content | | MCP Tool Integration | core/mcp/pool.py, services/tool_service.py | MCP lifecycle; command vs HTTP; timeout | | Skill Runtime | services/skill_executor.py, services/skill_service.py | Script exec; env var injection; enhanced vs local | | Chat Streaming | services/chat_service.py | SSE events; client disconnect; async save | | Memory System | services/unified_memory_manager.py | L1/L2; embedding scoring; slow queries |

Frontend Hot Zones

Zone	Files	Why It's High-Risk
SSE Chat Stream	INLINECODE22	Event parsing; reconnection; reasoning_content
Tool Call Rendering

features/chat/components/ToolCallCard.tsx | Dynamic display; error states; loading | | Skill Execution UI | features/chat/components/SkillExecutionInline.tsx | Inline status; progress; error display | | Markdown Renderer | features/chat/components/MarkdownRenderer.tsx | Nested code fences; special chars; XSS | | Agent Editor | features/agents/AgentEditorPage.tsx | Complex form state; tool/skill/KB associations | | Zustand Store | store/ | State updates not re-rendering if reference unchanged |

Two Code Paths for Agent Execution

CODEBLOCK11

When fixing anything in Path A, always check Path B for the same issue (and vice versa).

Known Duplicate Implementations

Function / Feature	Primary Location	Known Alternate Location
INLINECODE28	INLINECODE29	INLINECODE30
Tool loading / binding

services/agent_executor.py | core/graph/agent_graph.py | | Token counting | services/token_counter.py | May have inline counting in agent_executor.py | | Memory management | services/unified_memory_manager.py | core/graph/nodes/prepare_node.py |

OpenClaw Common Framework Pitfalls (Rule 7)

Area	Assumption	Reality
Config load order	First file has priority	Often last file wins (dict.update)
ORM lazy loading

Relations auto-load | Default lazy, causes N+1 | | Async on Windows | Same as Linux | Windows uses ProactorEventLoop; run_dev.py forces SelectorEventLoop | | Pydantic serialization | modeldump() includes all | excludeunset=True changes behavior | | LangChain tool binding | All models support tools | Reasoning models need simulated mode | | __pycache__ | Python uses latest source | Stale .pyc can persist across restarts |

Windows Development Environment Gotchas

Issue	Symptom	Workaround
Path separators	INLINECODE40 vs INLINECODE41	Use pathlib.Path or INLINECODE43
asyncio event loop

ProactorEventLoop default | run_dev.py forces loop="asyncio" | | __pycache__ file locks | Can't delete while running | Kill process FIRST, then clean | | Console encoding | GBK/CP936 default | sys.stdout.reconfigure(encoding='utf-8') | | Playwright on Windows | Browser launch may fail | Runs in separate thread with own loop |

---

Verification Commands (OpenClaw)

Backend

CODEBLOCK12

Frontend

CODEBLOCK13

Backend Server Restart

CODEBLOCK14

---

Reference Files

Living Data Files (update after every fix)

File	Purpose
INLINECODE48	Project-specific bug history
INLINECODE49

Single source of truth for AI blind spot registry |

Pattern Libraries (domain knowledge)

File	Purpose
INLINECODE50	Universal bug pattern library (11 categories)
INLINECODE51

Backend issues (API, ORM, LLM integration, OpenClaw-specific) | | references/frontend-patterns.md | Frontend issues (React hooks, race conditions, CORS) |

Detailed Guides

File	Purpose
INLINECODE53	System-level RCA (cross-layer, multi-process bugs)
INLINECODE54

Complete zero-regression verification matrix |

---

Skill Evolution

Update this skill when:

• - Code review finds a bug that the workflow should have prevented
• A recurring bug class repeats across fixes

Prefer updating specific sections over adding new rules.
After updates, validate that the workflow is still coherent and not overly bureaucratic.