\r \r

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

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

Iron Rules (12 — NEVER Violate)\r

\r

┌──────────────────────────────────────────────────────────────────────────┐\r
│  Rule 1:  Root cause MUST pass 4 gates before fixing                     │\r
│           (reproducible + causal + reversible + mechanistic)              │\r
│                                                                          │\r
│  Rule 2:  Scope MUST pass 5 gates before fixing                          │\r
│           (consumers + contracts + invariants + call sites + dup scan)    │\r
│                                                                          │\r
│  Rule 3:  MUST trace IMPACT CHAIN (code → data → time → event)          │\r
│           + scan ALL files for same pattern before writing fix            │\r
│                                                                          │\r
│  Rule 4:  MUST predict side effects + check blind spots before coding    │\r
│           (references/blind-spots.md is single source of truth)           │\r
│                                                                          │\r
│  Rule 5:  After fix, MUST run regression verification                    │\r
│           (functional + performance + concurrency + all impact levels)    │\r
│                                                                          │\r
│  Rule 6:  MUST verify fix is LOADED at runtime                           │\r
│           (clear __pycache__ + restart + exercise code path)              │\r
│                                                                          │\r
│  Rule 7:  Framework behavior → read source code first, never trust       │\r
│           docs/comments/assumptions alone                                │\r
│                                                                          │\r
│  Rule 8:  UI bugs MUST gather RUNTIME EVIDENCE before proposing fixes    │\r
│           (screenshot + DevTools DOM/console + user repro steps)          │\r
│           Do NOT fix UI bugs based on code reading alone.                │\r
│                                                                          │\r
│  Rule 9:  Fix is NOT done until: Bug Summary output + code-review        │\r
│           passes + knowledge files updated + self-reflection complete     │\r
│                                                                          │\r
│  Rule 10: Before fixing, CLASSIFY the problem layer:                     │\r
│           code bug? missing config? wrong architecture? AI capability?   │\r
│           Fix at the root layer, not at the symptom layer.               │\r
│                                                                          │\r
│  Rule 11: Pattern matching (regex, string match, name lookup) MUST       │\r
│           check boundary conditions (word boundaries / anchors / exact)   │\r
│                                                                          │\r
│  Rule 12: Before fix, MUST search bug pattern library + bug records      │\r
│           for known fixes and historical context                         │\r
└──────────────────────────────────────────────────────────────────────────┘\r
```\r
\r
---\r
\r
## Workflow Overview\r
\r
```\r
Phase 0: Triage → Severity (P0-P3) + Tier (Trivial/Standard/Complex)\r
  │\r
  ├─ Trivial → Quick Fix → test → done\r
  │\r
  ├─ Standard ─┐\r
  └─ Complex ──┘\r
      │\r
Phase 1: Reproduce (evidence required)\r
      │\r
Phase 2: Root Cause Analysis\r
    2A: Hypothesis ladder → 5 Whys → evidence\r
    2B: Search knowledge files (bug-patterns + bug-records)\r
    2C: Impact chain (code + data + time + event)\r
    2D: Similar issue scan across codebase\r
      │\r
Phase 3: Scope + Prediction\r
    3A: Consumer list → contracts → invariants → dup scan (5 gates)\r
    3B: Side effect prediction + blind spot check\r
    3C: Fix strategy comparison (when >10 LOC, Complex only)\r
      │\r
Phase 4: Fix (minimal change, prefer ≤50 LOC)\r
      │\r
Phase 5: Verify + Review\r
    5A: Regression verification (functional + perf + concurrency)\r
    5B: Runtime deployment verification\r
    5C: Bug Summary + code-review skill\r
      │\r
Phase 6: Knowledge Deposit + Self-Reflection\r
```\r
\r
---\r
\r
## Phase 0: Triage + Severity\r
\r
> Classify severity AND tier FIRST to control workflow depth.\r
\r
### Severity Classification (controls workflow depth)\r
\r
| Severity | Criteria | Workflow | Time-box |\r
|----------|----------|----------|----------|\r
| **P0 Critical** | Production down / data loss / security | FULL (all phases) | 4h escalation |\r
| **P1 High** | Core feature broken / data corruption | FULL (all phases) | 8h escalation |\r
| **P2 Medium** | Non-core feature / UI issue | STANDARD (skip 3C) | 16h |\r
| **P3 Low** | Cosmetic / minor edge case | QUICK (skip 2C, 2D, 3A-3C) | No limit |\r
\r
### Tier Classification (controls fix path)\r
\r
| Tier | Criteria | Path |\r
|------|----------|------|\r
| **Trivial** | Typo, config value, 1-line obvious fix, no behavioral change | Quick Fix (below) |\r
| **Standard** | Logic bug, 1-3 files, clear symptom, no cross-module risk | Standard Path (skip phases marked "Complex only") |\r
| **Complex** | Cross-module, >3 files, shared utility, schema change, multi-process | Full Path (all phases mandatory) |\r
\r
### Quick Fix Path (Trivial only)\r
\r
```markdown\r
## Quick Fix\r
- Bug: [one-line description]\r
- Fix: [one-line change]\r
- File: [path:line]\r
- Test: [how verified — lint/test/manual]\r
- Risk: None (isolated, no behavioral change)\r
```\r
\r
After quick fix: update `references/bug-records.md`, done. No RCA, no impact chain, no self-reflection needed.\r
\r
**If "trivial" fix touches >1 file or changes behavior → upgrade to Standard.**\r
\r
### Auto-Initialize Knowledge Files\r
\r
```\r
Check: references/bug-patterns.md exists?\r
  YES → search it in Phase 2B\r
  NO  → skip pattern search; create after first fix\r
\r
Check: references/bug-records.md exists?\r
  YES → search it in Phase 2B\r
  NO  → skip records search; create after first fix\r
\r
Check: references/blind-spots.md exists?\r
  YES → use it in Phase 3B\r
  NO  → skip blind spot check; create after first fix\r
```\r
\r
---\r
\r
## Phase 1: Reproduce\r
\r
> MUST have evidence before continuing. No evidence = no fix.\r
\r
| Bug Type | Evidence Required |\r
|----------|------------------|\r
| Backend error | Stack trace + request/response |\r
| Frontend UI | Screenshot + browser console + user repro steps (Rule 8) |\r
| Performance | Before/after metrics + profiler output |\r
| Intermittent | Timing conditions + frequency estimate |\r
\r
**UI Bug Protocol (Rule 8):**\r
1. Get user screenshot or screen recording\r
2. Open browser DevTools → check Console for errors/warnings\r
3. Inspect DOM structure (check for overflow clipping, z-index, Portal needs)\r
4. Reproduce the exact user steps\r
5. ONLY THEN form hypotheses\r
\r
### Evidence Bundle Template\r
\r
```markdown\r
### Trigger Conditions\r
- Input/params: [...]\r
- Environment: [OS/browser/runtime version]\r
- Timing: [action sequence or time interval]\r
\r
### Observable Output\r
- Error message: [full error text]\r
- Logs: [key log lines]\r
- Screenshot/recording: [if available]\r
\r
### Correlation IDs\r
- requestId/traceId: [...]\r
- sessionId: [...]\r
```\r
\r
---\r
\r
## Phase 2: Root Cause Analysis\r
\r
### 2A: Hypothesis Ladder\r
\r
| # | Hypothesis | Likelihood | Confirmation Test | Rejection Test | Status |\r
|---|-----------|-----------|-------------------|----------------|--------|\r
| 1 | [description] | High/Med/Low | [prove it IS this] | [prove it is NOT this] | [ ] |\r
\r
**Rules**: Sort by likelihood → each must be falsifiable → run rejection tests first → test ONE at a time → use 5 Whys to reach root cause.\r
\r
### Root Cause Confirmation Gate (Rule 1)\r
\r
Root cause is confirmed only when ALL 4 conditions are met:\r
\r
| Gate | Meaning |\r
|------|---------|\r
| **Reproducible** | Can trigger symptom in controlled scenario |\r
| **Causal** | Minimal change makes bug disappear |\r
| **Reversible** | Reverting the change makes bug reappear |\r
| **Mechanistic** | Can point to exact code path / state transition |\r
\r
### Framework Assumption Audit (Rule 7)\r
\r
When fix involves framework/library behavior: list assumptions → read source code to verify → document in comments with source references.\r
\r
### 2B: Search Knowledge Files (Rule 12)\r
\r
> Search bug-patterns.md and bug-records.md for matching patterns.\r
> Skip if files don't exist (see Phase 0 auto-init).\r
\r
| Match Level | Action |\r
|-------------|--------|\r
| High (symptom + root cause match) | Apply known fix, can skip remaining RCA |\r
| Medium (similar symptom) | Reference strategy, verify |\r
| No match | Full investigation, must deposit after fix |\r
\r
### 2C: Impact Chain (Rule 3)\r
\r
| Dimension | What to Check |\r
|-----------|---------------|\r
| **Code** | Bug file → direct callers → indirect callers → deep callers |\r
| **Data** | Corrupted records in DB/file/cache? Repair script needed? |\r
| **Time** | When introduced? Duration of exposure? Users affected? |\r
| **Event** | Message queues, WebSocket, background workers affected? |\r
\r
### 2D: Similar Issue Scan (Rule 3)\r
\r
> Scan ALL files for the same bug pattern, not just the reported file.\r
\r
```bash\r
rg -n "function_name\|similar_pattern" --glob "*.{ts,tsx,py,js}"\r
```\r
\r
---\r
\r
## Phase 3: Scope + Prediction\r
\r
### Scope Accuracy Gate (Rule 2)\r
\r
| # | Gate | Meaning |\r
|---|------|---------|\r
| 1 | **Consumer List** | All consumers (callers/dependents) enumerated |\r
| 2 | **Contract List** | Modified contracts/interfaces/behaviors listed |\r
| 3 | **Invariant Check** | Must-hold invariants listed |\r
| 4 | **Call Site Enum** | All call sites enumerated and classified |\r
| 5 | **Duplicate Scan** | No parallel implementation left unfixed |\r
\r
### 3A: Side Effect Prediction (Rule 4)\r
\r
1. **Change Blueprint** — What exactly will change\r
2. **Impact Ripple** — L0 (code) → L1 (module) → L2 (feature) → L3 (system) → L4 (user)\r
3. **Blind Spot Check** — Read `references/blind-spots.md` and execute every active check\r
4. **Go/No-Go Decision**\r
\r
**Quick version** (for Standard-tier, ≤5 LOC, 1 file):\r
```markdown\r
## Quick Impact Check\r
- Change: [one-line description]\r
- Direct callers: [list or "none - local function"]\r
- Duplicates: [checked — none / found and planned]\r
- Could break: [prediction or "low risk - isolated"]\r
- Decision: GO\r
```\r
\r
### 3B: Fix Strategy Comparison (>10 LOC, Complex only)\r
\r
| Dimension | Strategy A | Strategy B |\r
|-----------|-----------|-----------|\r
| LOC change | | |\r
| Impact scope | | |\r
| Regression risk | | |\r
| Rollback-able | | |\r
\r
---\r
\r
## Phase 4: Fix\r
\r
- Minimal change, prefer ≤50 LOC; justify if more\r
- ONE change at a time, never batch unrelated fixes\r
- **Layer Rule (Rule 10)**: Before writing fix code, verify you're fixing the right layer:\r
\r
| Problem in… | Fix… | Do NOT fix… |\r
|-------------|------|-------------|\r
| Params/config | Config or param passing | Business logic |\r
| Single component | That component | Framework |\r
| Multiple components same issue | Framework/base class | Each component one by one |\r
| Docs vs code mismatch | Both sides in sync | Only one side |\r
\r
- **Pattern matching safety (Rule 11)**: regex, string match, name lookup → always consider boundary conditions\r
- **DB schema change?** Generate Alembic migration:\r
  ```bash\r
  cd backend && alembic revision --autogenerate -m "describe change"\r
  ```\r
\r
---\r
\r
## Phase 5: Verify + Review\r
\r
### 5A: Regression Verification (Rule 5)\r
\r
| Category | Checks |\r
|----------|--------|\r
| **Functional** | Unit tests + integration + API + E2E + manual |\r
| **Performance** | No N+1 queries, no resource leaks, no response time increase |\r
| **Concurrency** | Thread-safe shared state, atomic operations, no race conditions |\r
\r
Test the entire impact chain (L0-L3), not just the original bug.\r
\r
### 5B: Runtime Deployment Verification (Rule 6)\r
\r
| Step | Action | Evidence |\r
|------|--------|----------|\r
| 1 | Clear Python bytecode cache | `__pycache__` removed |\r
| 2 | Restart backend service | PID changed from X to Y |\r
| 3 | Health check passes | `/docs` returns 200 |\r
| 4 | Exercise the fixed code path | Request triggers fixed logic |\r
\r
**If NOT deployed → restart and re-verify before proceeding.**\r
\r
### 5C: Bug Summary + Code Review (Rule 9)\r
\r
```markdown\r
## Bug Summary [BUG-XXX]\r
- **Symptom**: [one-sentence user-visible problem]\r
- **Root Cause**: [one-sentence actual cause]\r
- **Fix**: [one-sentence fix description]\r
- **Files Modified**: [file1.py, file2.ts]\r
- **Severity**: P0/P1/P2\r
```\r
\r
Output Bug Summary → run `code-review` skill → if review finds issues → fix → re-verify\r
\r
**Stop condition**: Code review clean + regression passed + deployment verified + original bug fixed.\r
\r
### Special Checks\r
\r
| Bug Type | Key Checks |\r
|----------|-----------|\r
| **API Bug** | Frontend → API → Schema → Service → DB chain; field completeness |\r
| **DB Migration** | Model changed → `alembic revision --autogenerate`; no migration = schema drift |\r
| **System-level** | Draw E2E chain; define handshake evidence per edge; insert probes first |\r
| **Cross-Surface** | Shared artifact → identify contract → consumer list → regression matrix |\r
\r
---\r
\r
## Phase 6: Knowledge Deposit + Self-Reflection\r
\r
### 6.1 Update Knowledge Files (Rule 9)\r
\r
| File | When to Update |\r
|------|---------------|\r
| `references/bug-records.md` | Every fix (project history) |\r
| `references/bug-patterns.md` | New pattern / new fix strategy (universal) |\r
| `references/blind-spots.md` | New blind spot discovered |\r
\r
### 6.2 Self-Reflection (Rule 9)\r
\r
| Dimension | Score (1-5) | Evidence |\r
|-----------|------------|----------|\r
| First-time correctness | [1-5] | Did the fix work on first attempt? |\r
| Scope accuracy | [1-5] | Did I find all affected areas? |\r
| Minimal change | [1-5] | Was the change as small as possible? |\r
| Side effect prediction | [1-5] | Did I predict all side effects? |\r
| Root cause depth | [1-5] | Did I fix root cause, not symptom? |\r
| **Total** | [/25] | |\r
\r
| Issue | What Happened | Why I Missed It | Prevention |\r
|-------|--------------|-----------------|------------|\r
\r
### Regression Autopsy (when fix introduced a regression)\r
\r
```markdown\r
- **Original Bug**: [what was being fixed]\r
- **New Bug Introduced**: [what broke]\r
- **Why I didn't predict it**: [blind spot]\r
- **Classification**: [missed consumer / contract violation / edge case / ...]\r
```\r
\r
---\r
\r
## Domain-Specific Checks\r
\r
| Bug Type | Key Checks |\r
|----------|-----------|\r
| **Backend/API** | Schema drift, timeout/retry, transactions, N+1, connection pool, ORM lazy loading |\r
| **Frontend/UI** | State (useEffect deps, unmount), race conditions, CORS, hydration, overflow/Portal |\r
| **System-level** | Cross-layer chain, async/streaming, IPC, routing |\r
| **Framework** | Read source code first (Rule 7), verify assumptions with tests |\r
| **AI/LLM** | Tool binding modes, simulated vs native, streaming, token limits |\r
\r
---\r
\r
## Skill Delegation\r
\r
| Trigger | Delegate To |\r
|---------|-----------|\r
| Need new API endpoint | fullstack-developer |\r
| UI fix needed | frontend-design |\r
| Schema change needed | database-migrations |\r
| After fix (mandatory) | code-review |\r
\r
---\r
\r
## Anti-Patterns (FORBIDDEN)\r
\r
| Forbidden | Correct |\r
|-----------|---------|\r
| Fix without RCA | Hypothesis ladder first |\r
| Single hypothesis then fix | List 3-5 hypotheses, verify each |\r
| Fix UI bug by code reading alone | Get runtime evidence first (Rule 8) |\r
| Skip consumer list for shared code | Fill consumer list first |\r
| Tests pass but server runs old code | Clear cache + restart + verify fix is live (Rule 6) |\r
| Fix code but ignore corrupted data | Assess data impact + repair if needed |\r
| Trust framework docs blindly | Read source code or run tests (Rule 7) |\r
| Fix one copy, miss the duplicate | Grep function name; check both Path A and Path B |\r
| Pattern match without boundary check | Add word boundaries / anchors / exact match (Rule 11) |\r
| Model changed but no migration | Run `alembic revision --autogenerate` |\r
| Use full workflow for a typo | Use Quick Fix path (Phase 0 Trivial tier) |\r
| Skip self-reflection | Must score, analyze, and learn |\r
\r
---\r
\r
## Final Checklist\r
\r
### Core (Standard + Complex tiers)\r
\r
| # | Check | Phase |\r
|---|-------|-------|\r
| 1 | Severity (P0-P3) + Tier (Trivial/Standard/Complex) classified | 0 |\r
| 2 | Root cause passes 4 gates | 2A |\r
| 3 | Bug pattern library + records searched | 2B |\r
| 4 | Impact chain traced (code+data+time+event) | 2C |\r
| 5 | Similar issue scan completed | 2D |\r
| 6 | Scope passes 5 gates (incl. duplicate scan) | 3A |\r
| 7 | Side effect prediction + blind spot check | 3A |\r
| 8 | Regression verification ALL passed (L0-L3) | 5A |\r
| 9 | Runtime deployment verified | 5B |\r
| 10 | Bug Summary output + code-review passed | 5C |\r
| 11 | Knowledge files updated | 6.1 |\r
| 12 | Self-reflection completed | 6.2 |\r
| 13 | If DB model changed: Alembic migration generated | 5 |\r
| 14 | User confirmed fix + no new bugs | Final |\r
\r
### Trivial Tier Checklist (Quick Fix path only)\r
\r
| # | Check | Status |\r
|---|-------|--------|\r
| 1 | Fix applied and tested (lint/test/manual) | [ ] |\r
| 2 | Bug record entry added | [ ] |\r
| 3 | No behavioral change introduced | [ ] |\r
\r
---\r
\r
## OpenClaw Project Context\r
\r
### Architecture Map\r
\r
```\r
backend/app/\r
├── api/v1/              # FastAPI routes (agents, auth, chat, skills, tools, profile)\r
├── core/\r
│   ├── graph/           # LangGraph StateGraph (agent_graph, nodes/llm_node, tool_node, prepare_node)\r
│   ├── langchain/       # LangChain tools (tools.py, shell_tool.py, e2b_tools.py)\r
│   ├── mcp/             # MCP server integration (pool.py)\r
│   ├── database.py      # SQLAlchemy async engine\r
│   └── security.py      # JWT auth\r
├── models/              # SQLAlchemy ORM models (agent, tool, user, skill)\r
├── schemas/             # Pydantic request/response schemas\r
├── services/            # Business logic (agent_executor, chat_service, tool_call_parser, ...)\r
├── middleware/           # Request logging, audit, error handling\r
└── main.py              # FastAPI app entry\r
\r
frontend/src/\r
├── features/            # Feature modules (chat, settings, admin, knowledge, skills, agents)\r
│   ├── chat/            # ChatPageV2, MessageRenderer, ToolCallCard, SkillExecutionInline\r
│   └── ...\r
├── components/ui/       # shadcn/ui style components (dialog, switch, checkbox)\r
├── hooks/               # React hooks (useChatStream — SSE event handling)\r
├── store/               # Zustand state management\r
└── lib/                 # API client (api-client.ts), markdown utils\r
```\r
\r
### Tech Stack\r
\r
| Layer | Technology |\r
|-------|-----------|\r
| Backend | FastAPI + Python 3.11+ |\r
| ORM | SQLAlchemy 2.0 (async) |\r
| DB | PostgreSQL (asyncpg) or MySQL (aiomysql) |\r
| Migrations | **Alembic** (`backend/alembic/`) |\r
| Cache | Redis |\r
| AI | LangChain 0.3.x + LangGraph 0.4.x |\r
| Vector DB | ChromaDB |\r
| Frontend | React 18 + Vite + TypeScript |\r
| UI | Radix UI + Tailwind CSS |\r
| State | Zustand + TanStack Query |\r
| Tests | pytest (backend), Vitest (frontend) |\r
| Deploy | Docker Compose, supports PyInstaller desktop build |\r
\r
### High-Risk Bug Zones\r
\r
#### Backend Hot Zones\r
\r
| Zone | Files | Why It's High-Risk |\r
|------|-------|--------------------|\r
| **Simulated Tool Call Parsing** | `services/tool_call_parser.py`, `core/graph/nodes/llm_node.py` | Regex-based; dual implementations; multi-arg edge cases |\r
| **Agent Executor** | `services/agent_executor.py` | 3000+ LOC; native + simulated modes; complex streaming |\r
| **Tool Argument Remapping** | `core/graph/nodes/tool_node.py` | LLM wrong param names → alphabetical guess |\r
| **LLM Streaming (httpx)** | `services/llm_manager.py` | Reasoning model fallback; SSE; reasoning_content |\r
| **MCP Tool Integration** | `core/mcp/pool.py`, `services/tool_service.py` | MCP lifecycle; command vs HTTP; timeout |\r
| **Skill Runtime** | `services/skill_executor.py`, `services/skill_service.py` | Script exec; env var injection; enhanced vs local |\r
| **Chat Streaming** | `services/chat_service.py` | SSE events; client disconnect; async save |\r
| **Memory System** | `services/unified_memory_manager.py` | L1/L2; embedding scoring; slow queries |\r
\r
#### Frontend Hot Zones\r
\r
| Zone | Files | Why It's High-Risk |\r
|------|-------|--------------------|\r
| **SSE Chat Stream** | `hooks/useChatStream.ts` | Event parsing; reconnection; reasoning_content |\r
| **Tool Call Rendering** | `features/chat/components/ToolCallCard.tsx` | Dynamic display; error states; loading |\r
| **Skill Execution UI** | `features/chat/components/SkillExecutionInline.tsx` | Inline status; progress; error display |\r
| **Markdown Renderer** | `features/chat/components/MarkdownRenderer.tsx` | Nested code fences; special chars; XSS |\r
| **Agent Editor** | `features/agents/AgentEditorPage.tsx` | Complex form state; tool/skill/KB associations |\r
| **Zustand Store** | `store/` | State updates not re-rendering if reference unchanged |\r
\r
### Two Code Paths for Agent Execution\r
\r
```\r
Path A: Direct Executor (most common)\r
  chat API → chat_service → agent_executor.py → tool_call_parser.py → tool execution\r
\r
Path B: StateGraph (LangGraph)\r
  chat API → chat_service → agent_graph.py → llm_node.py → tool_node.py → tool execution\r
```\r
\r
**When fixing anything in Path A, always check Path B for the same issue (and vice versa).**\r
\r
### Known Duplicate Implementations\r
\r
| Function / Feature | Primary Location | Known Alternate Location |\r
|--------------------|-----------------|-------------------------|\r
| `parse_simulated_tool_calls` | `services/tool_call_parser.py` | `core/graph/nodes/llm_node.py` |\r
| Tool loading / binding | `services/agent_executor.py` | `core/graph/agent_graph.py` |\r
| Token counting | `services/token_counter.py` | May have inline counting in `agent_executor.py` |\r
| Memory management | `services/unified_memory_manager.py` | `core/graph/nodes/prepare_node.py` |\r
\r
### OpenClaw Common Framework Pitfalls (Rule 7)\r
\r
| Area | Assumption | Reality |\r
|------|-----------|---------|\r
| Config load order | First file has priority | Often last file wins (dict.update) |\r
| ORM lazy loading | Relations auto-load | Default lazy, causes N+1 |\r
| Async on Windows | Same as Linux | Windows uses ProactorEventLoop; `run_dev.py` forces SelectorEventLoop |\r
| Pydantic serialization | model_dump() includes all | exclude_unset=True changes behavior |\r
| LangChain tool binding | All models support tools | Reasoning models need simulated mode |\r
| `__pycache__` | Python uses latest source | Stale `.pyc` can persist across restarts |\r
\r
### Windows Development Environment Gotchas\r
\r
| Issue | Symptom | Workaround |\r
|-------|---------|-----------|\r
| Path separators | `\` vs `/` | Use `pathlib.Path` or `os.path.join` |\r
| asyncio event loop | ProactorEventLoop default | `run_dev.py` forces `loop="asyncio"` |\r
| `__pycache__` file locks | Can't delete while running | Kill process FIRST, then clean |\r
| Console encoding | GBK/CP936 default | `sys.stdout.reconfigure(encoding='utf-8')` |\r
| Playwright on Windows | Browser launch may fail | Runs in separate thread with own loop |\r
\r
---\r
\r
## Verification Commands (OpenClaw)\r
\r
### Backend\r
\r
```bash\r
cd backend\r
ruff check app/                                    # Lint\r
python -m pytest tests/ -v --tb=short              # Unit tests\r
python -m pytest tests/test_specific.py -v         # Specific test\r
alembic revision --autogenerate -m "check"         # DB migration check\r
```\r
\r
### Frontend\r
\r
```bash\r
cd frontend\r
npm run lint\r
npm run typecheck\r
npm test\r
npm run build\r
```\r
\r
### Backend Server Restart\r
\r
```powershell\r
Get-WmiObject Win32_Process -Filter "Name='python.exe'" | Where { $_.CommandLine -like "*run_dev*" }\r
Stop-Process -Id [PID] -Force\r
Get-ChildItem -Path "backend" -Recurse -Filter "__pycache__" -Directory | Remove-Item -Recurse -Force\r
Start-Process -FilePath "backend\venv\Scripts\python.exe" -ArgumentList "run_dev.py" -WorkingDirectory "backend"\r
Invoke-WebRequest -Uri "http://127.0.0.1:8000/docs" -UseBasicParsing -TimeoutSec 5\r
```\r
\r
---\r
\r
## Reference Files\r
\r
### Living Data Files (update after every fix)\r
\r
| File | Purpose |\r
|------|---------|\r
| `references/bug-records.md` | Project-specific bug history |\r
| `references/blind-spots.md` | **Single source of truth** for AI blind spot registry |\r
\r
### Pattern Libraries (domain knowledge)\r
\r
| File | Purpose |\r
|------|---------|\r
| `references/bug-patterns.md` | Universal bug pattern library (11 categories) |\r
| `references/backend-patterns.md` | Backend issues (API, ORM, LLM integration, OpenClaw-specific) |\r
| `references/frontend-patterns.md` | Frontend issues (React hooks, race conditions, CORS) |\r
\r
### Detailed Guides\r
\r
| File | Purpose |\r
|------|---------|\r
| `references/system-rca.md` | System-level RCA (cross-layer, multi-process bugs) |\r
| `references/regression-matrix.md` | Complete zero-regression verification matrix |\r
\r
---\r
\r
## Skill Evolution\r
\r
Update this skill when:\r
- Code review finds a bug that the workflow should have prevented\r
- A recurring bug class repeats across fixes\r
\r
Prefer updating specific sections over adding new rules.\r
After updates, validate that the workflow is still coherent and not overly bureaucratic.\r