promote

---
name: promote
description: Use when graduating a proven pattern from auto-memory (MEMORY.md) to CLAUDE.md or .claude/rules/ for permanent enforcement.
category: Engineering
version: 1.0.0
tools: []
---

# Promote — Graduate Learnings to Rules

Move a proven pattern from auto-memory into the project's rule system, where it becomes enforced instruction.

## Workflow

### Step 1: Parse the Pattern

Extract from user input:
- **What**: The concrete fact or pattern
- **Why it matters**: Context
- **Scope**: Project-specific or global?

### Step 2: Search Auto-Memory

Find related entries in MEMORY.md. Show matching entries and confirm they match the user's intent.

### Step 3: Determine Target

| Pattern Scope | Target | Example |
|---|---|---|
| Entire project | `./CLAUDE.md` | "Use pnpm, not npm" |
| Specific file types | `.claude/rules/<topic>.md` | "API handlers need validation" |
| All projects | `~/.claude/CLAUDE.md` | "Prefer explicit error handling" |

### Step 4: Distill Rule

Transform from descriptive note to prescriptive instruction:
- One line per rule when possible
- Imperative voice: "Use X", "Always Y", "Never Z"
- Include the command or example, not just concept
- No backstory; just the instruction

Example:
- Before: "The project uses pnpm workspaces. When I tried npm install it failed."
- After: "Package manager: pnpm (not npm). Use `pnpm install`."

### Step 5: Write to Target

**For CLAUDE.md:**
1. Read existing CLAUDE.md
2. Find the appropriate section or create one
3. Append the new rule
4. If exceeding 200 lines, suggest `.claude/rules/` instead

**For `.claude/rules/`:**
1. Create file if missing
2. Add YAML frontmatter with `paths` if scoped
3. Write rule content

### Step 6: Clean Up Auto-Memory

After promoting, remove the original entry from MEMORY.md. Ask user to confirm.

### Step 7: Confirm Completion

Verify: rule distilled, written to target, removed from auto-memory, CLAUDE.md/rules updated.

## Promotion Decision Guide

### Promote When:
- Pattern appeared 3+ times in auto-memory
- Corrected Claude about it multiple times
- Any contributor should know it
- It prevents recurring mistakes

### Don't Promote When:
- One-time debugging note
- Session-specific context
- Might change soon
- Already covered by existing rules

## CLAUDE.md vs .claude/rules/

| Use CLAUDE.md for | Use .claude/rules/ for |
|---|---|
| Global project rules | File-type-specific patterns |
| Build commands | Testing conventions |
| Architecture decisions | API design rules |
| Team conventions | Framework-specific gotchas |