compound-learnings

# Compound Learnings

Transform ephemeral session learnings into permanent, compounding capabilities.

## When to Use

- "What should I learn from recent sessions?"
- "Improve my setup based on recent work"
- "Turn learnings into skills/rules"
- "What patterns should become permanent?"
- "Compound my learnings"

## Process

### Step 1: Gather Learnings

```bash
# List learnings (most recent first)
ls -t $CLAUDE_PROJECT_DIR/.claude/cache/learnings/*.md | head -20

# Count total
ls $CLAUDE_PROJECT_DIR/.claude/cache/learnings/*.md | wc -l
```

Read the most recent 5-10 files (or specify a date range).

### Step 2: Extract Patterns (Structured)

For each learnings file, extract entries from these specific sections:

| Section Header | What to Extract |
|----------------|-----------------|
| `## Patterns` or `Reusable techniques` | Direct candidates for rules |
| `**Takeaway:**` or `**Actionable takeaway:**` | Decision heuristics |
| `## What Worked` | Success patterns |
| `## What Failed` | Anti-patterns (invert to rules) |
| `## Key Decisions` | Design principles |

Build a frequency table as you go:

```markdown
| Pattern | Sessions | Category |
|---------|----------|----------|
| "Check artifacts before editing" | abc, def, ghi | debugging |
| "Pass IDs explicitly" | abc, def, ghi, jkl | reliability |
```

### Step 2b: Consolidate Similar Patterns

Before counting, merge patterns that express the same principle:

**Example consolidation:**
- "Artifact-first debugging"
- "Verify hook output by inspecting files"
- "Filesystem-first debugging"
→ All express: **"Observe outputs before editing code"**

Use the most general formulation. Update the frequency table.

### Step 3: Detect Meta-Patterns

**Critical step:** Look at what the learnings cluster around.

If >50% of patterns relate to one topic (e.g., "hooks", "tracing", "async"):
→ That topic may need a **dedicated skill** rather than multiple rules
→ One skill compounds better than five rules

Ask yourself: *"Is there a skill that would make all these rules unnecessary?"*

### Step 4: Categorize (Decision Tree)

For each pattern, determine artifact type:

```
Is it a sequence of commands/steps?
  → YES → SKILL (executable > declarative)
  → NO ↓

Should it run automatically on an event (SessionEnd, PostToolUse, etc.)?
  → YES → HOOK (automatic > manual)
  → NO ↓

Is it "when X, do Y" or "never do X"?
  → YES → RULE
  → NO ↓

Does it enhance an existing agent workflow?
  → YES → AGENT UPDATE
  → NO → Skip (not worth capturing)
```

**Artifact Type Examples:**

| Pattern | Type | Why |
|---------|------|-----|
| "Run linting before commit" | Hook (PreToolUse) | Automatic gate |
| "Extract learnings on session end" | Hook (SessionEnd) | Automatic trigger |
| "Debug hooks step by step" | Skill | Manual sequence |
| "Always pass IDs explicitly" | Rule | Heuristic |

### Step 5: Apply Signal Thresholds

| Occurrences | Action |
|-------------|--------|
| 1 | Note but skip (unless critical failure) |
| 2 | Consider - present to user |
| 3+ | Strong signal - recommend creation |
| 4+ | Definitely create |

### Step 6: Propose Artifacts

Present each proposal in this format:

```markdown
---

## Pattern: [Generalized Name]

**Signal:** [N] sessions ([list session IDs])

**Category:** [debugging / reliability / workflow / etc.]

**Artifact Type:** Rule / Skill / Agent Update

**Rationale:** [Why this artifact type, why worth creating]

**Draft Content:**
\`\`\`markdown
[Actual content that would be written to file]
\`\`\`

**File:** `.claude/rules/[name].md` or `.claude/skills/[name]/SKILL.md`

---
```

Use `AskUserQuestion` to get approval for each artifact (or batch approval).

### Step 7: Create Approved Artifacts

#### For Rules:
```bash
# Write to rules directory
cat > $CLAUDE_PROJECT_DIR/.claude/rules/<name>.md << 'EOF'
# Rule Name

[Context: why this rule exists, based on N sessions]

## Pattern
[The reusable principle]

## DO
- [Concrete action]

## DON'T
- [Anti-pattern]

## Source Sessions
- [session-id-1]: [what happened]
- [session-id-2]: [what happened]
EOF
```

#### For Skills:
Create `.claude/skills/<name>/SKILL.md` with:
- Frontmatter (name, description, allowed-tools)
- When to Use
- Step-by-step instructions (executable)
- Examples from the learnings

Add triggers to `skill-rules.json` if appropriate.

#### For Hooks:
Create shell wrapper + TypeScript handler:

```bash
# Shell wrapper
cat > $CLAUDE_PROJECT_DIR/.claude/hooks/<name>.sh << 'EOF'
#!/bin/bash
set -e
cd "$CLAUDE_PROJECT_DIR/.claude/hooks"
cat | node dist/<name>.mjs
EOF
chmod +x $CLAUDE_PROJECT_DIR/.claude/hooks/<name>.sh
```

Then create `src/<name>.ts`, build with esbuild, and register in `settings.json`:

```json
{
  "hooks": {
    "EventName": [{
      "hooks": [{
        "type": "command",
        "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/<name>.sh"
      }]
    }]
  }
}
```

#### For Agent Updates:
Edit existing agent in `.claude/agents/<name>.md` to add the learned capability.

### Step 8: Summary Report

```markdown
## Compounding Complete

**Learnings Analyzed:** [N] sessions
**Patterns Found:** [M]
**Artifacts Created:** [K]

### Created:
- Rule: `explicit-identity.md` - Pass IDs explicitly across boundaries
- Skill: `debug-hooks` - Hook debugging workflow

### Skipped (insufficient signal):
- "Pattern X" (1 occurrence)

**Your setup is now permanently improved.**
```

## Quality Checks

Before creating any artifact:

1. **Is it general enough?** Would it apply in other projects?
2. **Is it specific enough?** Does it give concrete guidance?
3. **Does it already exist?** Check `.claude/rules/` and `.claude/skills/` first
4. **Is it the right type?** Sequences → skills, heuristics → rules

## Files Reference

- Learnings: `.claude/cache/learnings/*.md`
- Skills: `.claude/skills/<name>/SKILL.md`
- Rules: `.claude/rules/<name>.md`
- Hooks: `.claude/hooks/<name>.sh` + `src/<name>.ts` + `dist/<name>.mjs`
- Agents: `.claude/agents/<name>.md`
- Skill triggers: `.claude/skills/skill-rules.json`
- Hook registration: `.claude/settings.json` → `hooks` section