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)

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