/si:promote — Graduate Learnings to Rules

Usage

/si:promote <pattern description>                    # Auto-detect best target
/si:promote <pattern> --target claude.md             # Promote to CLAUDE.md
/si:promote <pattern> --target rules/testing.md      # Promote to scoped rule
/si:promote <pattern> --target rules/api.md --paths "src/api/**/*.ts"  # Scoped with paths

Workflow

Step 1: Understand the pattern

• "What specific behavior should Claude follow?"
• "Does this apply to all files or specific paths?"

Step 2: Find the pattern in auto-memory

# Search MEMORY.md for related entries
MEMORY_DIR="$HOME/.claude/projects/$(pwd | sed 's|/|%2F|g; s|%2F|/|; s|^/||')/memory"
grep -ni "<keywords>" "$MEMORY_DIR/MEMORY.md"

Step 3: Determine the right target

./CLAUDE.md

.claude/rules/<topic>.md

~/.claude/CLAUDE.md

Step 4: Distill into a concise rule

The project uses pnpm workspaces. When I tried npm install it failed. The lock file is pnpm-lock.yaml. Must use pnpm install for dependencies.

## Build & Dependencies
- Package manager: pnpm (not npm). Use `pnpm install`.

• One line per rule when possible
• Imperative voice ("Use X", "Always Y", "Never Z")
• Include the command or example, not just the concept
• No backstory — just the instruction

Step 5: Write to target

1. Read existing CLAUDE.md
2. Find the appropriate section (or create one)
3. Append the new rule under the right heading
4. If file would exceed 200 lines, suggest using

   .claude/rules/

   instead

.claude/rules/

1. Create the file if it doesn't exist
2. Add YAML frontmatter with

   paths

   if scoped
3. Write the rule content

---
paths:
  - "src/api/**/*.ts"
  - "tests/api/**/*"
---

# API Development Rules

- All endpoints must validate input with Zod schemas
- Use `ApiError` class for error responses (not raw Error)
- Include OpenAPI JSDoc comments on handler functions

Step 6: Clean up auto-memory

# Show what will be removed
grep -n "<pattern>" "$MEMORY_DIR/MEMORY.md"

Step 7: Confirm

✅ Promoted to {{target}}

Rule: "{{distilled rule}}"
Source: MEMORY.md line {{n}} (removed)
MEMORY.md: {{lines}}/200 lines remaining

The pattern is now an enforced instruction. Claude will follow it in all future sessions.

Promotion Decision Guide

Promote when:

• Pattern appeared 3+ times in auto-memory
• You corrected Claude about it more than once
• It's a project convention that any contributor should know
• It prevents a recurring mistake

Don't promote when:

• It's a one-time debugging note (leave in auto-memory)
• It's session-specific context (session memory handles this)
• It might change soon (e.g., during a migration)
• It's already covered by existing rules

CLAUDE.md vs .claude/rules/

Tips

• Keep CLAUDE.md under 200 lines — use rules/ for overflow
• One rule per line is easier to maintain than paragraphs
• Include the concrete command, not just the concept
• Review promoted rules quarterly — remove what's no longer relevant