learn

name	learn
description	Manage project learnings across sessions. Save, search, recall, digest, prune, and export learnings that compound over time. Use when user wants to record, recall, or share project knowledge.
argument-hint	<save|search|recall|digest|list|prune|export> [query]
allowed-tools	Bash, Read, Write, Grep

Project Learnings Manager

Learnings are structured knowledge that compounds across sessions. They capture what worked, what didn't, decisions made, and patterns discovered — things that can't be derived from code alone.

Announce at start: "I'm using the learn skill to manage project learnings."

Commands

Save a learning

When the user discovers something worth remembering — a debugging insight, an architecture decision, a deployment gotcha, a tool preference:

node ${CLAUDE_PLUGIN_ROOT}/tools/learnings-manager.mjs save --title "Title here" --body "Detailed learning content" --tags "tag1,tag2"

What to save:

• Debugging insights ("Redis connection pool exhausts at 50 concurrent requests")
• Architecture decisions and their rationale ("Chose BullMQ over pg-boss because...")
• Deployment gotchas ("Railway needs NODE_ENV=production explicitly set")
• Performance findings ("Drizzle select() is 3x faster than query() for simple lookups")
• Integration quirks ("Polar.sh webhooks retry 3x with exponential backoff")

What NOT to save:

• Code patterns (read the code instead)
• Git history (use git log)
• Temporary debugging state (that's for the current session)

Search learnings

node ${CLAUDE_PLUGIN_ROOT}/tools/learnings-manager.mjs search --query "keyword"

Search by title, body content, or tags. Returns all matches, unranked.

Recall the most relevant learnings (ranked)

node ${CLAUDE_PLUGIN_ROOT}/tools/learnings-manager.mjs recall --query "keyword" [--limit N]

Prefer recall over search when you want the most relevant prior knowledge, not every match. It ranks by relevance (title > tag > body) with recency breaking ties, returns the top N (default 5) with one-line summaries and a score. Use this BEFORE starting work on a topic — it surfaces the learnings most likely to prevent a repeated mistake without dumping the whole history into context.

Digest the whole knowledge base (compression)

node ${CLAUDE_PLUGIN_ROOT}/tools/learnings-manager.mjs digest

Produces a compact, grouped-by-topic snapshot — one line per learning, primary tag only — so a long history stays readable in a few tokens. Inject this at session start (or after a compaction) to carry forward what the project has learned without re-reading every learning file. This is the long-session memory primitive: digest to load context cheaply, recall to drill into a topic.

List all learnings

node ${CLAUDE_PLUGIN_ROOT}/tools/learnings-manager.mjs list [--limit N]

Prune old learnings

node ${CLAUDE_PLUGIN_ROOT}/tools/learnings-manager.mjs prune --older-than 90

Removes learnings older than N days. Default: 90 days. Run periodically to keep the knowledge base fresh.

Export learnings

node ${CLAUDE_PLUGIN_ROOT}/tools/learnings-manager.mjs export --format markdown
node ${CLAUDE_PLUGIN_ROOT}/tools/learnings-manager.mjs export --format json

Export for sharing with team members or backing up before a major refactor.

Workflow Integration

At session start: Run digest to load a compact snapshot of what the project has learned, then recall --query "<topic>" when the user names a specific area — load cheap context first, drill in on demand.

After debugging: Save the root cause and fix as a learning — it will save hours next time.

After deployment issues: Save the gotcha — deployment problems recur.

Before major changes: Search for past learnings about the affected area.

During retrospectives: Use with /retro to cross-reference velocity data with learnings.

Storage

Learnings are stored in .ultraship/learnings/ in the project directory as JSON files. Each learning has:

• id — unique identifier
• title — short, searchable title
• body — detailed content
• tags — categorization for filtering
• created_at / updated_at — timestamps

Add .ultraship/ to .gitignore if you don't want learnings in version control, or commit them to share with your team.