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