keel-distill

/keel-distill — the memory consolidation ritual ("sleep" for the project)

Run when HANDOVER.md exceeds 3 session blocks / ~150 lines, when LESSONS.md exceeds ~250 or TASKS.md ~100 lines, or when any of them is over its KB cap (one long line can overflow a file that is green on lines — the SessionStart hook warns on all of these), or every ~5 sessions as hygiene — that cadence is yours to keep, the hook only detects cap overflows. Memory that is written but never reviewed degrades the project — consolidation is what keeps it useful (rules.md §9).

Propose the full plan, get user approval, then apply. Never lossy-delete. (File-TREE clutter — stray scripts, logs, dead code — is not this ritual's job: that is /keel-tidy, §3.10.)

1. Rotate HANDOVER blocks (oldest first, until ≤2 blocks AND under the line cap AND the KB cap)

For each block being rotated, triage by criticality — content-aware, not age-blind:

• (b) Tried, didn't work → PERMANENT: distill each to one LESSONS.md [fail] line (<date> — <approach> → FAILED: <reason>. (full trace: docs/handover-archive.md, block <date>)).
• Open questions live in HANDOVER's global section, not in blocks — leave them until resolved.
• (a) Completed → nothing to move: git history + the archive keep it.
• (c) Latest updates → superseded by newer blocks — nothing to promote; the verbatim archive keeps it.
• (d) Next steps of an old block → dead (that work is done or re-planned) — no promotion.
• Then move the WHOLE block verbatim to the TOP of docs/handover-archive.md (prepend, newest first — restorable compression: the distilled lines keep pointers back to it).

2. Consolidate LESSONS.md (write-policy: add / update / retire / promote-and-delete — never LOSSY delete)

• Scope-triage every entry first (A/B/C/D — the LESSONS header defines the tiers): always-relevant stays; file-scoped graduates (below); a permanent domain fact → docs; superseded/closed/already- promoted → DELETE. Field measurement behind the triage: in a mature file ~52% of entries were file-scoped and any one task needed ~15% of the file — the always-on core is the minority (reports/2026-08-17-lessons-scope-audit.md).
• Merge duplicates and near-duplicates into the stronger phrasing (keep the earliest date).
• Start where the SessionStart hook pointed: above 70% of the cap it names the OLDEST unpromoted entries and the inflow since the last distill. Those are the triage queue — ask of each: still true → promote (below) · proven wrong → retire · resolved → delete. A file with an inflow valve and no worked exit sits at its cap forever (measured: three distills in four days, count still rising 123 → 129, not one entry ever retired).
• Retire what proved WRONG — move the entry VERBATIM to the top of docs/lessons-retired.md with a RETIRED <date>: <what refuted it · what is true instead · evidence path> line, and leave ONE corrective line here ("believed X — measured Y → retired"). Never a SUPERSEDED stub: the original text keeps paying rent in an always-loaded file for knowledge known to be false, while the one-line correction is what stops a session re-learning it.
• Promote what has graduated: a lesson applied 3+ times is no longer a lesson — move it into rules.md (conduct), a .claude/skills/ skill (procedure), an ADR (decision), or — for a permanent DOMAIN fact (a data quirk, an API contract) — the relevant docs (docs/architecture.md "known limitations" / a guide). A lesson CLUSTER that binds only SPECIFIC files (a must-run test after touching X, an append-only dir, a never-hand-edit generated file) becomes a path-scoped rule — .claude/rules/<name>.md with paths: frontmatter: it loads ONLY when a matching file is touched, so it is cheaper than both rules.md and this file — or a paths:-scoped SKILL (.claude/skills/<name>/SKILL.md, same paths: format) when the cluster must SURVIVE a mid-task compaction: invoked skill bodies are the one scoped mechanism re-injected after compaction (≈5k tokens/skill, 25k total, truncation keeps the TOP — put the load-bearing lines first), while a path rule waits for the next file match. Never put must-always-hold discipline in either (that stays in LESSONS tier A / rules.md). The new rule/skill is shown as its FULL text in the distill plan and lands owner-approved, written self-contained — constraint + why + check inline, evidence pointing only to permanent artifacts, never to TASKS/PLAN live state (.claude/rules/README.md "Writing discipline").
• Promotion DELETES the LESSONS entry — lossless: the content lives in its target and git keeps the history. Never leave a "moved to X" stub (field case: 10 promoted entries left 42 lines of stubs, taxing every session). The ONE surviving pointer is a line in LESSONS ## Index (what → where → when it loads) — add or refresh it in the same pass. This is the main pressure valve on a long project's [gotcha] list: reference facts belong in docs, file-scoped stock behind its trigger — not in the always-loaded core.