learn

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.