bug-fixing

Zero-regression bug fix workflow: triage → reproduce → root cause → impact analysis → fix → verify → knowledge deposit → self-reflect. Use when: - Feature broken, incorrect behavior, wrong output, errors/exceptions - Console errors/warnings even when feature appears functional - Regressions, timeouts, degraded performance - Keywords: "fix bug", "debug", "not working", "error", "broken" Output: Bug summary + verification report + code review + self-reflection score. Not for: new features (use fullstack-developer); pure review (use code-review); optimization (use performance-optimization).

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)

text

┌──────────────────────────────────────────────────────────────────────────┐
│  Rule 1:  Root cause MUST pass 4 gates before fixing                     │
│           (reproducible + causal + reversible + mechanistic)              │
│                                                                          │
│  Rule 2:  Scope MUST pass 5 gates before fixing                          │
│           (consumers + contracts + invariants + call sites + dup scan)    │
│                                                                          │
│  Rule 3:  MUST trace IMPACT CHAIN (code → data → time → event)          │
│           + scan ALL files for same pattern before writing fix            │
│                                                                          │
│  Rule 4:  MUST predict side effects + check blind spots before coding    │
│           (references/blind-spots.md is single source of truth)           │
│                                                                          │
│  Rule 5:  After fix, MUST run regression verification                    │
│           (functional + performance + concurrency + all impact levels)    │
│                                                                          │
│  Rule 6:  MUST verify fix is LOADED at runtime                           │
│           (clear __pycache__ + restart + exercise code path)              │
│                                                                          │
│  Rule 7:  Framework behavior → read source code first, never trust       │
│           docs/comments/assumptions alone                                │
│                                                                          │
│  Rule 8:  UI bugs MUST gather RUNTIME EVIDENCE before proposing fixes    │
│           (screenshot + DevTools DOM/console + user repro steps)          │
│           Do NOT fix UI bugs based on code reading alone.                │
│                                                                          │
│  Rule 9:  Fix is NOT done until: Bug Summary output + code-review        │
│           passes + knowledge files updated + self-reflection complete     │
│                                                                          │
│  Rule 10: Before fixing, CLASSIFY the problem layer:                     │
│           code bug? missing config? wrong architecture? AI capability?   │
│           Fix at the root layer, not at the symptom layer.               │
│                                                                          │
│  Rule 11: Pattern matching (regex, string match, name lookup) MUST       │
│           check boundary conditions (word boundaries / anchors / exact)   │
│                                                                          │
│  Rule 12: Before fix, MUST search bug pattern library + bug records      │
│           for known fixes and historical context                         │
└──────────────────────────────────────────────────────────────────────────┘

---

Workflow Overview

text

Phase 0: Triage → Severity (P0-P3) + Tier (Trivial/Standard/Complex)
  │
  ├─ Trivial → Quick Fix → test → done
  │
  ├─ Standard ─┐
  └─ Complex ──┘
      │
Phase 1: Reproduce (evidence required)
      │
Phase 2: Root Cause Analysis
    2A: Hypothesis ladder → 5 Whys → evidence
    2B: Search knowledge files (bug-patterns + bug-records)
    2C: Impact chain (code + data + time + event)
    2D: Similar issue scan across codebase
      │
Phase 3: Scope + Prediction
    3A: Consumer list → contracts → invariants → dup scan (5 gates)
    3B: Side effect prediction + blind spot check
    3C: Fix strategy comparison (when >10 LOC, Complex only)
      │
Phase 4: Fix (minimal change, prefer ≤50 LOC)
      │
Phase 5: Verify + Review
    5A: Regression verification (functional + perf + concurrency)
    5B: Runtime deployment verification
    5C: Bug Summary + code-review skill
      │
Phase 6: Knowledge Deposit + Self-Reflection

---

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)

markdown

## Quick Fix
- Bug: [one-line description]
- Fix: [one-line change]
- File: [path:line]
- Test: [how verified — lint/test/manual]
- Risk: None (isolated, no behavioral change)

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

text

Check: references/bug-patterns.md exists?
  YES → search it in Phase 2B
  NO  → skip pattern search; create after first fix

Check: references/bug-records.md exists?
  YES → search it in Phase 2B
  NO  → skip records search; create after first fix

Check: references/blind-spots.md exists?
  YES → use it in Phase 3B
  NO  → skip blind spot check; create after first fix

---

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. 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

markdown

### Trigger Conditions
- Input/params: [...]
- Environment: [OS/browser/runtime version]
- Timing: [action sequence or time interval]

### Observable Output
- Error message: [full error text]
- Logs: [key log lines]
- Screenshot/recording: [if available]

### Correlation IDs
- requestId/traceId: [...]
- sessionId: [...]

---

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.

bash

rg -n "function_name\|similar_pattern" --glob "*.{ts,tsx,py,js}"

---

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. 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):

markdown

## Quick Impact Check
- Change: [one-line description]
- Direct callers: [list or "none - local function"]
- Duplicates: [checked — none / found and planned]
- Could break: [prediction or "low risk - isolated"]
- Decision: GO

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:

  bash

  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	__pycache__ 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)

markdown

## Bug Summary [BUG-XXX]
- **Symptom**: [one-sentence user-visible problem]
- **Root Cause**: [one-sentence actual cause]
- **Fix**: [one-sentence fix description]
- **Files Modified**: [file1.py, file2.ts]
- **Severity**: P0/P1/P2

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
references/bug-records.md	Every fix (project history)
references/bug-patterns.md	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)

markdown

- **Original Bug**: [what was being fixed]
- **New Bug Introduced**: [what broke]
- **Why I didn't predict it**: [blind spot]
- **Classification**: [missed consumer / contract violation / edge case / ...]

---

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

text

backend/app/
├── api/v1/              # FastAPI routes (agents, auth, chat, skills, tools, profile)
├── core/
│   ├── graph/           # LangGraph StateGraph (agent_graph, nodes/llm_node, tool_node, prepare_node)
│   ├── langchain/       # LangChain tools (tools.py, shell_tool.py, e2b_tools.py)
│   ├── mcp/             # MCP server integration (pool.py)
│   ├── database.py      # SQLAlchemy async engine
│   └── security.py      # JWT auth
├── models/              # SQLAlchemy ORM models (agent, tool, user, skill)
├── schemas/             # Pydantic request/response schemas
├── services/            # Business logic (agent_executor, chat_service, tool_call_parser, ...)
├── middleware/           # Request logging, audit, error handling
└── main.py              # FastAPI app entry

frontend/src/
├── features/            # Feature modules (chat, settings, admin, knowledge, skills, agents)
│   ├── chat/            # ChatPageV2, MessageRenderer, ToolCallCard, SkillExecutionInline
│   └── ...
├── components/ui/       # shadcn/ui style components (dialog, switch, checkbox)
├── hooks/               # React hooks (useChatStream — SSE event handling)
├── store/               # Zustand state management
└── lib/                 # API client (api-client.ts), markdown utils

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	services/tool_call_parser.py, core/graph/nodes/llm_node.py	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	hooks/useChatStream.ts	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

text

Path A: Direct Executor (most common)
  chat API → chat_service → agent_executor.py → tool_call_parser.py → tool execution

Path B: StateGraph (LangGraph)
  chat API → chat_service → agent_graph.py → llm_node.py → tool_node.py → tool execution

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
parse_simulated_tool_calls	services/tool_call_parser.py	core/graph/nodes/llm_node.py
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	model_dump() includes all	exclude_unset=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	\ vs /	Use pathlib.Path or os.path.join
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

bash

cd backend
ruff check app/                                    # Lint
python -m pytest tests/ -v --tb=short              # Unit tests
python -m pytest tests/test_specific.py -v         # Specific test
alembic revision --autogenerate -m "check"         # DB migration check

Frontend

bash

cd frontend
npm run lint
npm run typecheck
npm test
npm run build

Backend Server Restart

powershell

Get-WmiObject Win32_Process -Filter "Name='python.exe'" | Where { $_.CommandLine -like "*run_dev*" }
Stop-Process -Id [PID] -Force
Get-ChildItem -Path "backend" -Recurse -Filter "__pycache__" -Directory | Remove-Item -Recurse -Force
Start-Process -FilePath "backend\venv\Scripts\python.exe" -ArgumentList "run_dev.py" -WorkingDirectory "backend"
Invoke-WebRequest -Uri "http://127.0.0.1:8000/docs" -UseBasicParsing -TimeoutSec 5

---

Reference Files

Living Data Files (update after every fix)

File	Purpose
references/bug-records.md	Project-specific bug history
references/blind-spots.md	Single source of truth for AI blind spot registry

Pattern Libraries (domain knowledge)

File	Purpose
references/bug-patterns.md	Universal bug pattern library (11 categories)
references/backend-patterns.md	Backend issues (API, ORM, LLM integration, OpenClaw-specific)
references/frontend-patterns.md	Frontend issues (React hooks, race conditions, CORS)

Detailed Guides

File	Purpose
references/system-rca.md	System-level RCA (cross-layer, multi-process bugs)
references/regression-matrix.md	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.