Lessons prune

Prune LESSONS.md

Facilitate a structured review of LESSONS.md to cut entries that waste context without preventing real problems.

Before you start

1. Read the LESSONS.md in scope in full. A repo may have more than one: a cross-cutting root LESSONS.md plus co-located nested ones (e.g. tools/zep/LESSONS.md). Prune the file the user pointed at, or the root by default. Note that siblings exist, but don't merge them — each is scoped to its subtree on purpose. An entry that only matters in another subtree's area is misplaced, not shared (see the table below).

2. Read context files — check for and read any that exist: CLAUDE.md, AGENTS.md, and your auto-memory (e.g. .claude/memory/MEMORY.md). These are your redundancy references — if something is already covered there, it doesn't need to also be in LESSONS.

3. Ask about niche tools — "Are any of the tools/frameworks in this file new or poorly documented? For niche projects, I'll raise the bar for cutting entries since you can't easily Google the answers." This matters because the decision tree below short-circuits on "can you Google it" — niche tools need a different threshold.

4. Assess current size and set a target:

   • Per-section: 1-5 entries max. If a section has >5, it needs splitting or pruning.
   • Total file target by project type:
     • Normal project: 40-80 lines
     • Multi-tool project (several distinct services/tools): 60-100 lines
     • Monorepo: up to ~150 lines
   • If the file is >2x the target, it's overdue.

5. Establish a clean git baseline. Prune is destructive, so the pre-prune state must be its own recoverable commit before you cut anything. Check git status for LESSONS.md:

   • Dirty (uncommitted edits): commit it first, scoped — git add LESSONS.md && git commit -m "context(lessons): checkpoint before prune". Never git add -A.
   • Clean: HEAD is already your baseline; nothing to do.

   This guarantees every entry you're about to cut is preserved at a known SHA, recoverable with one command — instead of depending on a later auto-backup sweep.

Review approach

Scale interactivity to file size:

• Under 50 lines or ≤3 sections: Present the full classification at once. One round of user approval.
• Larger files: Go section-by-section, waiting for user approval before proceeding to the next.

Classify every entry

Category	Action	What it means
Sharp	Keep	Would cause a real bug, wasted debug session, or repeated correction without it
Dull	Cut	Obvious, easily Googled, or vague enough that any model already knows it
Misplaced	Flag	Belongs in another file (CLAUDE.md, auto-memory, another repo's LESSONS)
Redundant	Merge/cut	Already stated in CLAUDE.md, auto-memory, or another entry in the same file

Decision tree for each entry

Apply these filters in order — short-circuit as soon as one matches:

1. Is it already stated in CLAUDE.md or auto-memory?
   → Yes: cut (redundant)

2. Is the error message self-descriptive?
   → Yes: cut (you'd figure it out from the error)

3. Can you find the answer in <1 min of searching?
   → Yes (well-documented tool): cut
   → No (niche/new tool with poor docs): continue ↓

4. Did this cost real time?
   → Silent failure with no error message? → keep
   → Misleading error that sends you down the wrong path? → keep
   → Persistent model behavior the user repeatedly corrects? → keep
   → >15 min to diagnose even knowing where to look? → keep
   → No to all: cut

Counter-aware pruning

Entries with usage counters provide a signal:

• (0) entries that have been around for multiple sessions — "never proven useful" candidates. Ask the user before cutting — the lesson may be preventive (you never hit the bug because the entry exists).
• High-count (N) entries — proven value. Strong keep signal.
• Entries without counters — legacy format. Classify normally, add (0) if kept.

Format note: use - (N), never - [N] — (N) is the counter convention across these skills. (Square brackets also render as checkboxes in Obsidian.)

Merge heuristic

• Same error/symptom, different root causes → combine into one diagnostic entry
• Same tool/API, genuinely different failure modes → keep separate

Present classifications to the user

For each section (or all at once for small files), show:

• Sharp (keep): entries + why they're worth the context
• Dull (cut): entries + why they're safe to remove
• Misplaced (move): entries + where they belong instead
• Redundant (merge/cut): entries + what they duplicate

Also flag any [ADD], [UPDATE], [REMOVE] tags or (was: ...) changelog lines to strip — these are review artifacts that shouldn't persist.

After review is complete

1. Rescue pass — Do one final scan of everything you're cutting. Specifically ask: "Any of these cuts look like hard-earned lessons that would be painful to relearn?" Present the full cut list so the user can do a quick visual scan.

2. Apply all edits in a single pass. Write the cleaned file.

3. Normalize format — ensure all kept entries follow the standard format: - (N) **tool/context** — insight. Action. Add (0) counters to any legacy entries missing them.

4. Strip all changelog artifacts — remove [ADD], [UPDATE], [REMOVE] tags and (was: ...) lines from the final output.

5. Commit the pruned file — scoped, immediately, so the prune is its own atomic, identifiable commit rather than getting swept into an unrelated auto-backup commit. List what was cut so a wrongly-removed lesson is greppable in git log later:

   git add LESSONS.md
   git commit -m "context(lessons): prune — cut N, kept M" -m "cut: <bold tag of cut entry 1>
   cut: <bold tag of cut entry 2>"
   

   The context(lessons): subject and per-line cut: <bold tag> body follow the ledger grammar (see the lessons skill's Commit protocol) — a prune is one semantic op, so it stays a single commit, but each cut tag on its own cut: line keeps every removed entry greppable via git log --grep '<tag>'. Only ever add the specific LESSONS.md you pruned (use its real path for a nested file, e.g. git add tools/zep/LESSONS.md) — never git add -A; other dirty files belong to other uncommitted work. Skip the commit only on a true no-op (nothing changed). If pruning empties a nested LESSONS.md entirely, flag its @import pointer in the co-located CLAUDE.md for removal rather than leaving a dangling import. After committing, register the repo in the machine-wide ledger index:

   mkdir -p ~/.claude/context-ledger
   r=$(git rev-parse --show-toplevel)
   grep -qxF "$r" ~/.claude/context-ledger/repos 2>/dev/null || echo "$r" >> ~/.claude/context-ledger/repos
   

6. Verify it landed — run git status and git log -1 --stat; confirm LESSONS.md is clean and the prune commit exists. Do not claim the prune is done until you've seen the clean status and the commit. (Evidence before assertions.)

7. Report the results — show before/after line counts, per-section breakdown, where misplaced entries should go (but don't move them — just recommend), and the recovery line: the prune commit SHA plus git revert <sha> to undo the entire prune in one step.

What does NOT belong in LESSONS.md

These have better homes:

Content	Better home	Why
Architecture, repo structure, commands	CLAUDE.md	Describes what the repo is
Preferences, decisions, project state	Auto-memory	Guides how to approach work
Gotchas only relevant in another repo	That repo's LESSONS.md	Only matters when coding there
Gotchas only relevant in another subdirectory's area	That subdir's co-located LESSONS.md	Keep the root file cross-cutting; push area-specific lessons down
General advice ("design before coding")	Nowhere — too generic	Any model already knows this
One-time fixes already applied	Nowhere — stale	The fix is in the code

What DOES belong in LESSONS.md

Entries that pass this test: "Would I hit a specific, non-obvious problem or waste significant time without this?"

Good entries identify a specific tool/context, a specific problem (failure mode, persistent wrong behavior, or convention), and a specific action. The best ones describe situations where the obvious approach consistently leads you astray.