consolidate-lessons

Consolidate Lessons

/extract-lessons only ever adds (newer supersedes older on direct contradiction). Over many runs the archive accumulates near-duplicate active lessons and dead superseded files. This command does the periodic cleanup the extract loop can't: it merges overlapping lessons, splits compound ones whose sub-tips are invisible downstream, and prunes stale ones, so INDEX.md stays signal-dense.

Argument: $ARGUMENTS

• empty (default): propose a consolidation plan and apply it after listing the changes.
• dry-run: produce the plan only, list proposed merges/prunes, change nothing.
• a category (e.g. agents): scope consolidation to lessons/<category>/ only.

Steps

1. Load the archive:

   • Read lessons/INDEX.md and lessons/README.md (for the file format + supersession rules).
   • Glob lessons/**/*.md (exclude INDEX.md, README.md). Read each one's frontmatter (id, status, category, supersedes/superseded_by, created) and TL;DR.

2. Spawn Explore subagents to find redundancy and buried sub-tips (keep the bulk reading out of main context). One subagent suffices up to ~150 active lessons; above that, fan out over category batches, all launched in one message. Give each the per-lesson {id, category, status, tldr, created} records for its batch plus the full active slug list for dedupe, and ask it to return JSON identifying:

   • merge clusters: 2+ active lessons that cover the same idea and should become one canonical lesson (e.g. several "keep it under 200 lines" lessons). Pick the strongest as canonical; the rest get superseded by it. Same-claim redundancy ONLY: never merge two distinct actionable claims into one body, since that bundling is exactly the burial the split pass below exists to undo.
   • split candidates: an active lesson whose body carries one or more independently-actionable sub-tips absent from its title and TL;DR (a setting, a hook, a keyboard habit inside a bigger workflow's body). The subagent must read candidate bodies, not just TL;DRs. Downstream routing (/optimise habits, /top-tips tracing) reads titles and TL;DRs, so a buried sub-tip never surfaces; this pass is the retroactive counterpart of the /extract-lessons §5 atomicity rule for the corpus mined before 2026-08-29. A split-out tip that duplicates an existing active lesson is not a split, it is already covered: skip it.
   • stale: lessons whose advice is outdated/contradicted or whose feature no longer exists.
   • Tell it: be conservative, only cluster lessons that are genuinely redundant, not merely adjacent. Distinct nuances stay separate.

   {
     "merges": [
       {"canonical_id": "keep-context-lean", "merge_in": ["id-a", "id-b"], "merged_tldr": "...", "merged_body": "...", "reason": "..."}
     ],
     "splits": [
       {"source_id": "compound-lesson-slug",
        "new_lessons": [{"id": "sub-tip-slug", "title": "...", "tldr": "...", "why": "...", "how": "...", "category": "workflows", "tool": "claude-code"}],
        "reason": "..."}
     ],
     "prune_stale": [ {"id": "...", "reason": "..."} ]
   }