Distill

---
name: distill
description: Extract reusable principles and decision frameworks from accumulated experience. Use after significant work sessions, project milestones, or when you notice recurring patterns worth codifying.
argument-hint: [domain or topic to distill]
user-invocable: true
allowed-tools: Read, Glob, Grep, Bash
---

Distill wisdom from experience in this area: $ARGUMENTS

## Process

### 1. Experience Inventory

Gather evidence of past decisions and outcomes:
- Read recent git history (`git log --oneline -20`)
- Review agent memory and learnings
- Check `.claude/rules/` for existing principles
- Look at code patterns in the codebase

### 2. Pattern Extraction

For each significant decision or outcome:
- **What was decided?** (the choice made)
- **What was the context?** (constraints, information available)
- **What happened?** (outcome, downstream effects)
- **Was it the right call?** (with hindsight)

Look for:
- **Success patterns** — conditions that consistently lead to good outcomes
- **Failure patterns** — early warning signs of bad paths
- **Evolution patterns** — how thinking has changed over time

### 3. Principle Abstraction

Distill patterns into principles at the right abstraction level:

| Level | Example |
|---|---|
| **Tactical** | "Always run tests before committing database migrations" |
| **Strategic** | "Prefer reversible changes over irreversible ones" |
| **Philosophical** | "Optimize for time-to-signal, not time-to-completion" |

A good principle is:
- **Actionable** — you can act on it right now
- **Falsifiable** — you can identify situations where it doesn't apply
- **Bounded** — it states when it applies, not just what to do

### 4. Validation

Check each principle against past experience:
- Does it explain observed outcomes?
- Are there counter-examples?
- Under what conditions does it break?

### 5. Storage

Write validated principles to the appropriate location:
- **Project-wide**: `.claude/rules/` as a new or updated rule file
- **Agent-specific**: Agent memory
- **Session-specific**: `MEMORY.md`

Tag with freshness: **HOT** (just validated) | **WARM** (reasonable but not recently tested) | **COLD** (theoretical)

### 6. Output

```
## Distillation: [Domain]

### Evidence Base
- [N decisions/outcomes reviewed]
- [Key sources consulted]

### Principles Extracted

#### [Principle Name]
- **Statement**: [Clear, actionable principle]
- **Level**: tactical | strategic | philosophical
- **Evidence**: [What experience supports this]
- **Boundary**: [When this does NOT apply]
- **Freshness**: HOT | WARM | COLD
- **Stored in**: [where it was written]

### Principles Updated
- [Any existing principles promoted, demoted, or retired]

### Open Questions
- [What we still don't know]
```