/si:promote — Graduate Learnings to Rules
Moves a proven pattern from Claude's auto-memory into the project's rule system, where it becomes an enforced instruction rather than a background note.
Usage
/si:promote # Auto-detect best target
/si:promote --target claude.md # Promote to CLAUDE.md
/si:promote --target rules/testing.md # Promote to scoped rule
/si:promote --target rules/api.md --paths "src/api/*/.ts" # Scoped with paths
Workflow
Step 1: Understand the pattern
Parse the user's description. If vague, ask one clarifying question:
"What specific behavior should Claude follow?"
"Does this apply to all files or specific paths?"
Step 2: Find the pattern in auto-memory
MEMORY_DIR
"
$HOME
/.claude/projects/
$(
pwd
|
sed
's|/|%2F|g; s|%2F|/|; s|^/||'
)
/memory"
grep
-ni
""
"
$MEMORY_DIR
/MEMORY.md"
Show the matching entries and confirm they're what the user means.
Step 3: Determine the right target
Pattern scope
Target
Example
Applies to entire project
./CLAUDE.md
"Use pnpm, not npm"
Applies to specific file types
.claude/rules/.md
"API handlers need validation"
Applies to all your projects
~/.claude/CLAUDE.md
"Prefer explicit error handling"
If the user didn't specify a target, recommend one based on scope.
Step 4: Distill into a concise rule
Transform the learning from auto-memory's note format into CLAUDE.md's instruction format:
Before
(MEMORY.md — descriptive):
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.
After
(CLAUDE.md — prescriptive):
Build & Dependencies
Package manager: pnpm (not npm). Use
pnpm install
.
Rules for distillation:
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
For CLAUDE.md:
Read existing CLAUDE.md
Find the appropriate section (or create one)
Append the new rule under the right heading
If file would exceed 200 lines, suggest using
.claude/rules/
instead
For
.claude/rules/
:
Create the file if it doesn't exist
Add YAML frontmatter with
paths
if scoped
Write the rule content
paths
:
-
"src/api//*.ts"
-
"tests/api//*"
API Development Rules
Use
ApiError
class for error responses (not raw Error)
-
Include OpenAPI JSDoc comments on handler functions
Step 6: Clean up auto-memory
After promoting, remove or mark the original entry in MEMORY.md:
Show what will be removed
grep
-n
""
"
$MEMORY_DIR
/MEMORY.md"
Ask the user to confirm removal. Then edit MEMORY.md to remove the promoted entry. This frees space for new learnings.
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/
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
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