Learnings Loop — Self-Improving Memory

How It Works

This skill creates a feedback loop where each session builds on previous knowledge.

At Session Start

Check if learnings.md exists in the project root:

cat learnings.md 2>/dev/null | head -50

If it exists, read it and apply those learnings to your current work.

During Work — Record When You Discover:

• A codebase convention not documented elsewhere
• A bug pattern and its root cause
• A library quirk or workaround
• An architecture decision and the reasoning
• A performance insight
• A testing pattern that works well here

At Session End — Update learnings.md:

Append new entries using this format:

### [Date] — [Category]
**Context**: [What were you working on]
**Learning**: [What you discovered]
**Evidence**: [File/commit where this applies]
**Impact**: [How this should influence future work]

Categories

• convention — How things are done here (naming, patterns, structure)
• gotcha — Something that looks right but is wrong; avoid this trap
• pattern — A successful approach worth reusing
• decision — An architecture/design choice and why it was made
• performance — Something that affects speed/memory/bundle size
• workaround — A hack needed because of a bug/limitation elsewhere

Promotion Rules

When a learning has been validated across 3+ sessions:

• Promote it to CLAUDE.md or .claude/rules/ for automatic loading
• Remove it from learnings.md to keep the file lean
• learnings.md should stay under 100 entries

Weekly Consolidation

Run /user:consolidate-learnings weekly to:

1. Review all entries
2. Merge duplicates
3. Promote validated patterns
4. Archive stale entries