learnings

ADD Learnings Skill v{{VERSION}}

Manage the learnings knowledge base: generate optimized active views, archive stale entries, and report statistics.

Overview

Learnings accumulate over time in .add/learnings.json and ~/.claude/add/library.json. The full JSON files are expensive to load into agent context. This skill manages the lifecycle:

• migrate — Generate compact -active.md views from existing JSON (or migrate legacy .md to JSON first)
• archive — Mark old low-severity entries as archived to shrink the active set
• stats — Show learning counts, sizes, and context savings

Default subcommand (no argument): migrate.

Pre-Flight Checks

1. Read .add/config.json to get project name
2. Locate learnings files:
   • .add/learnings.json (Tier 3 project learnings)
   • .add/learnings.md (legacy or generated view)
   • .add/learnings-active.md (optimized active view)
   • ~/.claude/add/library.json (Tier 2 cross-project)
   • ~/.claude/add/library-active.md (Tier 2 active view)

Subcommand: migrate

Generate -active.md files from existing JSON. Handles three scenarios:

Scenario A: JSON exists, active view missing or stale

This is the most common case — existing projects upgrading to the active view approach.

1. Run ${CLAUDE_PLUGIN_ROOT}/hooks/filter-learnings.sh on .add/learnings.json
2. Run ${CLAUDE_PLUGIN_ROOT}/hooks/filter-learnings.sh on ~/.claude/add/library.json (if it exists)
3. Report what was generated and the context savings

Scenario B: Only legacy .md exists (no JSON)

Pre-v0.4.0 projects that never migrated to structured JSON.

1. Announce: "Found legacy markdown learnings — migrating to JSON first."
2. Back up .add/learnings.md to .add/learnings.md.pre-migration.bak
3. Parse the markdown:
   • Each - **[{severity}] {title}** line is an entry
   • Extract body text from indented continuation lines
   • If no structured format, treat each ## section + bullet as an entry
4. For each parsed entry, create a JSON learning object:
   • Assign ID: L-001, L-002, etc.
   • Infer category from section heading (Anti-Patterns → anti-pattern, Technical → technical, etc.)
   • Infer severity from [critical], [high], [medium], [low] markers. Default: medium
   • Set scope: project
   • Set stack: [] (stack-agnostic, can be refined during retro)
   • Set source: project name from config
   • Set date: extract from entry if present, otherwise use file modification date
   • Set classified_by: agent
   • Set checkpoint_type: retro (migrated entries treated as retro-sourced)
5. Write .add/learnings.json with the standard wrapper
6. Run ${CLAUDE_PLUGIN_ROOT}/hooks/filter-learnings.sh on the new JSON
7. Report: entries migrated, JSON created, active view generated