Cavekit Revision

# Revision: Tracing Bugs Back to Kits

In Cavekit, revision means tracing a production defect upstream through the cavekit chain until you find the gap that allowed it. In practice, when the built software has bugs or gaps, you trace the issue back to the kits and prompts and fix at the source -- not just in code.

**Key insight:** When a fix lives only in code with no corresponding cavekit update, the next iteration loop may reintroduce the same defect. The goal is that kits plus the iteration loop can reproduce any fix autonomously.

---

## 1. Why Revision Matters

Without revision, every bug fix is a one-off patch. The next time the iteration loop runs, it may reintroduce the bug because nothing in the kits or plans prevents it.

With revision:
- Bug fixes become **cavekit improvements** that persist across all future iterations
- The iteration loop becomes **self-correcting** -- it learns from every manual intervention
- Kits become **progressively more complete** over time
- The gap between "what kits describe" and "what works" **shrinks monotonically**

```
Without revision:
  Bug found -> Fix code -> Bug may return next iteration

With revision:
  Bug found -> Fix code -> Update cavekit -> Re-run iteration loop -> Fix emerges from kits alone
```

---

## 2. The 6-Step Revision Process

This is the complete process for tracing a bug back to its cavekit-level root cause and closing the loop.

### Step 1: Identify and Fix the Defect

Locate the bug -- whether through manual testing, automated failures, user reports, or monitoring alerts -- and resolve it through normal debugging. This produces a working code change, but the job is far from done: until the underlying cavekit gap is closed, this fix is fragile.

```bash
# The fix produces commits that we will analyze
git log --oneline -5
# a1b2c3d Fix: connection pool exhaustion under concurrent load
# e4f5g6h Fix: missing rate limit headers in API responses
```

### Step 2: Analyze What the Cavekit Missed

This is the pivotal step. Ask: **"Where in the cavekit chain did this requirement slip through?"**

Break the analysis into five dimensions:
- **WHAT** changed (files, functions, observable behavior)
- **WHY** it was wrong (which assumption proved false)
- **VISUAL** — does this fix change visual appearance (CSS, styling, layout)? If yes, check whether DESIGN.md covers the pattern. A missing design pattern is a design system gap that should be fixed alongside the cavekit gap.
- **The RULE** (the invariant that should have been stated)
- **The LAYER** (which cavekit, plan, or prompt should have contained this)

Example analysis:

```markdown
## Revision Analysis: Database Connection Pooling

**WHAT changed:** Added pool size limits and idle timeout in `src/db/pool.ts`
**WHY:** The data layer cavekit assumed unlimited connections; under load the database
         rejected new connections once the server-side limit was reached
**RULE:** "The database module MUST configure a bounded connection pool with
          idle timeout and max-connection limits matching the deployment target"
**LAYER:** cavekit-data.md (no mention of pool configuration), plan-data.md (no task for pool tuning)
**Cavekit implications:** Add requirement R5 to cavekit-data.md covering connection pool settings
```

### Step 3: Update the Cavekit

Add the missing requirement or constraint to the appropriate cavekit file. Focus on acceptance criteria that are concrete enough for the iteration loop to act on:

```markdown
# In context/kits/cavekit-data.md, add:

### R5: Database Connection