bug-fixing-openclaw

---
name: bug-fixing-openclaw
description: |
  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).
allowed-tools: [read, write, execute, grep, glob]
metadata:
  language: en
  version: 4.0.0
  last_updated: 2026-03-06
  platform: openclaw
  enhancement:
    - v4.0 Iron Rules 20→12 (attention-dilution fix, aligned with bug-fixing v4.0)
    - v4.0 Rule 8 NEW — UI bugs require runtime evidence before fix
    - v4.0 Rule 10 NEW — Classify problem layer before fixing
    - v4.0 Phase 0 adds P0-P3 severity + auto-initializes knowledge files
    - v4.0 Severity-adaptive workflow depth (P0=full, P3=quick)
    - v4.0 Domain-Specific Checks consolidated table
    - v4.0 Kept OpenClaw project context, hot zones, Windows gotchas
---

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

```
┌──────────────────────────────────────────────────────────────────────────┐
│  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

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

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

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

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