Skip to main content

​
/learn-rule Command

Capture a lesson from this session into permanent memory. The /learn-rule command is the core of the self-correction loop — every correction becomes a rule that prevents future mistakes.

​
Syntax

/learn-rule
/learn-rule <rule>
Examples: 
/learn-rule
/learn-rule Navigation: Confirm full path when multiple files share a name

​
The Self-Correction Process

1

Identify the Lesson

What went wrong?
  • What mistake was made?
  • What should have happened instead?
  • What would prevent this next time?
Example:
  • Mistake: Edited src/utils.ts when user meant src/lib/utils.ts
  • Should: Confirm full path before editing files with common names
2

Format the Rule

Use the standard learning format:
[LEARN] Category: One-line rule
Categories:
  • Navigation — File paths, finding code
  • Editing — Code changes, patterns
  • Testing — Test approaches
  • Git — Commits, branches
  • Context — Memory, compaction
  • Tools — MCP servers, CLI flags
  • Prompting — How to ask Claude
  • Architecture — Design decisions
Example:
[LEARN] Navigation: Confirm full path before editing files with common names
3

Save to Database

The command saves the learning to SQLite:
INSERT INTO learnings (
  category,
  rule,
  context,
  project,
  created_at
) VALUES (
  'Navigation',
  'Confirm full path before editing files with common names',
  '<session context>',
  'my-app',
  '2026-03-08 10:30:00'
)
Indexed for FTS5 search: The rule is searchable via /search and surfaces automatically via /replay.
4

Update CLAUDE.md (Optional)

For critical learnings, add to CLAUDE.md:
## LEARNED

### Navigation
- Confirm full path before editing files with common names
- Use Glob first to list all matches before Read
This ensures the rule loads in every session, not just on demand.

​
Learning Categories

File paths and code location: 
[LEARN] Navigation: Confirm full path before editing files with common names
[LEARN] Navigation: Use Glob first to list all matches before Read
[LEARN] Navigation: Check both src/ and lib/ for utility functions

​
Editing

Code changes and patterns: 
[LEARN] Editing: Always add error handling when calling external APIs
[LEARN] Editing: Use const assertions for string literal types
[LEARN] Editing: Prefer early returns over nested conditionals

​
Testing

Test approaches and patterns: 
[LEARN] Testing: Mock external API calls in unit tests
[LEARN] Testing: Test edge cases first, happy path last
[LEARN] Testing: Use describe blocks to group related tests

​
Git

Commits, branches, and workflows: 
[LEARN] Git: Run quality gates before every commit
[LEARN] Git: Use feat(scope) format for commit messages
[LEARN] Git: Never force push to main branch

​
Context

Memory and compaction: 
[LEARN] Context: Compact at task boundaries, not mid-task
[LEARN] Context: Check /context before starting heavy exploration
[LEARN] Context: Use /replay at session start to load relevant learnings

​
Tools

MCP servers and CLI: 
[LEARN] Tools: Keep &lt;10 MCP servers active for performance
[LEARN] Tools: Use --worktree flag for parallel sessions
[LEARN] Tools: Disable unused MCPs with disabledMcpServers

​
Example Flow

> I corrected Claude for editing the wrong file again.

Acknowledged. I edited src/utils.ts when you meant src/lib/utils.ts.

[LEARN] Navigation: Confirm full path before editing files with common names

Should I save this to the database?

> yes

> /learn-rule

Extracting lesson from correction...

Identified:
  Mistake: Edited wrong file (src/utils.ts vs src/lib/utils.ts)
  Category: Navigation
  Rule: Confirm full path before editing files with common names

Saving to database...
✓ Saved learning #47

Add to CLAUDE.md? (y/n)
> y

Updating CLAUDE.md...
✓ Added to ## LEARNED > Navigation

This learning will now:
  1. Surface in /search navigation
  2. Surface in /replay before related tasks
  3. Load in every session (via CLAUDE.md)

​
Database Schema

Learnings are stored with full-text search: 
CREATE TABLE learnings (
  id INTEGER PRIMARY KEY,
  category TEXT NOT NULL,
  rule TEXT NOT NULL,
  context TEXT,
  project TEXT,
  created_at TEXT DEFAULT CURRENT_TIMESTAMP
);

CREATE VIRTUAL TABLE learnings_fts USING fts5(
  rule,
  context,
  content='learnings',
  content_rowid='id'
);
Search uses BM25 ranking for relevance. See Database API for details.

​
Integration with Other Commands

​
With /wrap-up

Wrap-up suggests learnings to capture: 
> /wrap-up

[3/5] Learning Capture
─────────────────────

Corrections this session:
  1. Fixed file path confusion (src/utils.ts)
  2. Added missing error handling
  
Suggested learnings:
  [LEARN] Navigation: Confirm full path before editing files with common names
  [LEARN] Editing: Always add error handling when calling external APIs
  
Save these learnings? (y/n)

​
With /replay

Replay surfaces past learnings: 
> /replay refactor authentication

Surfacing relevant learnings...

From 3 days ago:
  [LEARN] Testing: Mock external API calls in unit tests
  Context: When refactoring auth middleware
  
From 1 week ago:
  [LEARN] Editing: Always add error handling when calling external APIs
  Context: Fixed auth error handling

​
With /search

Search finds learnings by keyword: 
> /search file paths

Found 3 learnings:

#47 [Navigation] Confirm full path before editing files with common names
    Created: 2 days ago
    Project: my-app
    
#23 [Navigation: Use Glob first to list all matches before Read
    Created: 1 week ago
    Project: my-app

​
Best Practices

Capture Every Correction

Don’t skip corrections. Every mistake is a learning opportunity that compounds.

Be Specific

Vague rules don’t help. “Check file paths” is worse than “Confirm full path before editing files with common names”.

Use Right Category

Correct categorization helps /replay surface relevant learnings.

Update CLAUDE.md

Add critical learnings to CLAUDE.md so they load in every session.

​
Troubleshooting

If learnings aren’t saving:
  1. Check database exists: 
    ls ~/.pro-workflow/data.db
  2. Initialize if missing: 
    cd ~/.claude/plugins/*/pro-workflow
npm run db:init
  3. Check permissions: 
    chmod 644 ~/.pro-workflow/data.db
If past learnings don’t surface:
  1. Check FTS5 index: 
    SELECT * FROM learnings_fts WHERE rule MATCH 'your-keyword';
  2. Rebuild index: 
    DELETE FROM learnings_fts;
INSERT INTO learnings_fts(learnings_fts) VALUES('rebuild');
  3. Verify search works: 
    /search your-keyword
If CLAUDE.md exceeds 150 lines:
  1. Keep only top 10-20 critical learnings in CLAUDE.md
  2. Let other learnings surface on-demand via /replay
  3. Split into modules if needed (see Split Memory)

/replay

Surface past learnings before starting work

/search

Search learnings database by keyword

/list

List all stored learnings

Learn Rule Skill

Deep dive on learning capture

​
Next Steps

Build docs developers (and LLMs) love

Get started for freeTalk to us