/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.