webproxy/.claude/RUNBOOK.md

# UnicornDev Agent Runbook

> Quick reference for consistent, reliable behavior. Consult this at every phase.

---

## Session Start Checklist

```
□ Load .claude/settings.json
□ Load .claude/knowledge/index.json
□ Note project type and current state
□ Check for pending tasks
□ Initialize meta-cognition monitoring
```

---

## Request Classification

```
USER INPUT
    │
    ├─► TASK (do something)
    │   ├─ Feature → Spec first?
    │   ├─ Bug → Debug skill
    │   ├─ Question → Explore
    │   └─ Refactor → Plan first
    │
    ├─► QUESTION (explain something)
    │   ├─ About code → Read/explore
    │   ├─ About tech → Check knowledge
    │   └─ How to → May need to learn
    │
    └─► FEEDBACK (response to our work)
        ├─ Approval → Continue
        ├─ Correction → Update, maybe learn
        └─ Rejection → Stop, understand why
```

---

## Complexity Assessment (Before Starting Tasks)

```
QUICK COMPLEXITY CHECK:

Single file + known solution + low risk?
├─► YES → TRIVIAL: Just do it
└─► NO → Full assessment needed
```

### Full Assessment

```
Rate 1-5 each, then average:

SCOPE:        1=one function ... 5=multiple systems
UNCERTAINTY:  1=known solution ... 5=unprecedented
DEPENDENCIES: 1=none ... 5=complex chain
RISK:         1=safe ... 5=critical
KNOWLEDGE:    1=fully known ... 5=unknown territory

Score 1.0-1.5: TRIVIAL  → Direct execution
Score 1.6-2.5: SIMPLE   → Light planning
Score 2.6-3.5: MODERATE → Task list, verify each
Score 3.6-4.5: COMPLEX  → Phases, checkpoints, regression tests
Score 4.6-5.0: EXTREME  → Prove each step, user checkpoints
```

### Methodology by Level

```
TRIVIAL:  Do → Verify → Done
SIMPLE:   Plan (mental) → Do → Test → Done
MODERATE: Tasks → [Do → Verify → Check regression]* → Done
COMPLEX:  Phases → [Do → Verify → Full regression → Checkpoint]* → Done
EXTREME:  Prove approach → Phases → [Verify continuously]* → Done
```

### Decomposition Rules

```
□ Each increment ≤ 30 minutes
□ Each increment independently verifiable
□ Each increment revertable
□ No increment leaves system broken
```

---

## Verification Levels

```
L0: Compiles? (tsc --noEmit, build)
L1: Unit works? (test function/component)
L2: Integrates? (works with dependencies)
L3: End-to-end? (user flow works)
L4: No regressions? (existing tests pass)

TRIVIAL:  L0
SIMPLE:   L0 + L1
MODERATE: L0 + L1 + L2 + L4
COMPLEX:  L0 + L1 + L2 + L3 + L4
EXTREME:  All levels, continuously
```

### Regression Response

```
IF regression found:
1. STOP immediately
2. Identify what broke
3. Assess severity (critical/major/minor)
4. Critical/Major → REVERT, then reassess
5. Minor → Quick fix if <5min, else revert
```

---

## Before Every Action

```
□ Is this the right approach?
□ Do I have what I need?
□ Will this move us forward?

If unsure → PAUSE, don't guess
```

---

## Every 10 Actions: Meta-Check

```
FLOW STATE CHECK:

GREEN (continue):
  ✓ Making progress
  ✓ Actions succeeding
  ✓ Clear direction

YELLOW (caution):
  ⚠ Some uncertainty
  ⚠ Minor retries
  ⚠ Searching without finding
  → Pause, assess

RED (stop):
  ✗ Stuck
  ✗ Repeated failures
  ✗ No clear next action
  → Full reflection required
```

---

## Trigger Quick Reference

### Learn System
| Trigger | Action |
|---------|--------|
| Unknown package in package.json | Research + document |
| Unknown import in code | Research + document |
| "How do I use X?" | Check knowledge, learn if missing |
| Web search reveals new tech | Document key patterns |

### Reflect System
| Trigger | Action |
|---------|--------|
| Same error 3x | STOP → Diagnose → Fix |
| Same search 3x | Switch to exploration pattern |
| No progress 5 actions | Pause → Reflect |
| 3+ files without completing any | Focus on one thing |

### Knowledge System
| Trigger | Action |
|---------|--------|
| Task involves known tech | Load relevant knowledge |
| Decision point | Check for relevant patterns |
| About to implement | Check for anti-patterns |

---

## Decision Framework

### Approach Selection
```
1. Check knowledge base for patterns
2. Consider simplest approach first
3. If multiple options, weigh trade-offs
4. If uncertain, ask or research
5. Document decision reasoning
```

### Blocker vs Optimization
```
Can I proceed without fixing this?
├─► NO (blocker) → Fix now
└─► YES → Is slowdown > 50%?
          ├─► YES + quick fix → Fix now
          └─► Otherwise → Queue for later
```

### When to Ask User
```
ASK when:
- Requirements are ambiguous
- Multiple valid approaches exist and preference matters
- Destructive action needed
- Stuck after 3 recovery attempts

DON'T ASK when:
- Answer is in codebase
- Standard approach exists
- Can make reasonable assumption
```

---

## Recovery Procedures

### Search Loop (3+ similar searches)
```
1. STOP searching
2. Read package.json for libraries
3. List directory structure
4. Find entry points, follow trail
5. Use systematic exploration pattern
```

### Error Loop (3+ same error)
```
1. STOP retrying
2. Log the error
3. Ask: Why is this failing?
4. Ask: What assumption is wrong?
5. Try different approach
```

### Stuck (no clear next action)
```
1. STOP everything
2. Re-read original request
3. What is the smallest next step?
4. Do ONLY that step
5. Verify it worked before continuing
```

---

## Quality Gates

### Before Delivering Code
```
□ Does it compile/run?
□ Does it handle errors?
□ Is it typed correctly?
□ Does it follow project patterns?
□ Does it match the request?
```

### Before Creating Files
```
□ Is this file necessary?
□ Does similar file already exist?
□ Is the location correct?
□ Is the naming consistent?
```

### Before Completing Task
```
□ All acceptance criteria met?
□ No TODOs left unaddressed?
□ Would I approve this PR?
```

---

## Self-Improvement Protocol

### After Every Task
```
1. Quick review: What went well? What didn't?
2. If struggled with something → Create pattern
3. If learned something new → Add to knowledge
4. If found better approach → Document it
```

### Improvement Types
| Situation | Create |
|-----------|--------|
| Recurring task difficulty | .claude/skills/{name}.md |
| Missing technology info | .claude/knowledge/{cat}/{name}.md |
| Reusable solution | .claude/knowledge/patterns/{name}.md |
| Default not working | Update .claude/settings.json |

---

## Logging Requirements

### Always Log
- Session start/end
- Task start/completion
- Errors encountered
- Reflections triggered
- Improvements made
- Major decisions

### Log Location
```
.claude/logs/
├─ session-{date}-{id}.jsonl   # Session events
├─ reflections.jsonl           # Reflection events
├─ improvements-queue.jsonl    # Queued improvements
└─ reviews/                    # Post-task reviews
```

---

## Emergency Procedures

### Completely Lost
```
1. Stop all actions
2. Say: "I'm having trouble. Let me reassess."
3. Re-read original request
4. List what has been done
5. Identify the gap
6. Take smallest possible next step
```

### Breaking Changes Risk
```
1. Stop before executing
2. Warn user explicitly
3. Explain what could break
4. Wait for confirmation
5. Create backup plan
```

### Unknown Territory
```
1. Acknowledge uncertainty
2. Research before acting
3. Start with smallest experiment
4. Verify before scaling
```

---

## Key Principles

1. **Progress over perfection** - Move forward, iterate
2. **Detect and correct** - Notice problems early, fix fast
3. **Learn and improve** - Every struggle is a learning opportunity
4. **When in doubt, stop** - Pausing beats failing forward
5. **Simplest path first** - Complexity is earned, not assumed