Keel Distill

---
name: keel-distill
description: Consolidate project memory — rotate old HANDOVER blocks to the archive, promote critical facts to LESSONS.md, dedup/merge, and lint for contradictions. Run when caps are exceeded.
---

# /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.

- **COOL what is still true but no longer cited** — the third exit, for the entry that is neither
  wrong (retire) nor applied often enough to promote, yet earns no line in a file every session pays
  for. Proxy criterion, labelled as one: is the entry cited from `## Index` or from any report / spec
  / ADR (`grep -rl` its key phrase)? Not cited → move it VERBATIM (with its date) to
  `docs/retro/<YYYY-MM>.md` and leave ONE router line in `## Index`. Cooling is not deletion and not
  retirement (`docs/retro/README.md`). Field origin: a file stuck at 1000/1000 for weeks because the
  entry budget throttled the inflow while nothing opened an outflow; 82 of its 132 entries were
  single-copy knowledge, so the exit had to be worked per entry, never as a bulk sweep.

## 3. Prune TASKS.md
- Verify done items were deleted (their one-liner lives in HANDOVER (a)); delete any stragglers.
- **Drain `## Discovered` to convergence** (incl. project variants like `## Discovered-team`) — it is
  an INBOX, not storage: each line → `## Next` (real task, with done-when) · `docs/` known-limitations
  / R-request doc (domain/provider fact) · `LESSONS.md` (lesson) · an ADR (design decision) · DELETE
  (resolved/superseded — git keeps it). One line per entry; longer → a report/ADR + pointer here. A
  line surviving TWO distills is in the wrong file — after this step the section holds only the
  current week's untriaged finds. Refill `## Now` (max 3–5, per person on teams).

## 4. Sweep closed team reports to done/ (folder hygiene — orchestrator/owner only)
A long-running author folder drowns its open work: dozens of spec/fix files, no visual way to tell
finished from in-flight. The valve: a report whose task reached **`closed <date> accepted|rejected`**
in the index moves to its author's **`reports/team/<@tag>/done/`** — the flat folder then holds only
live work, and "what is @X still carrying?" becomes a directory listing again.

- **Only `closed` moves.** `wip · delivered · verified` are in flight — on the board, cited from
  `## Review` (the reground hook checks those paths against disk), never swept.
- **A move is `git mv` + citation rewrite, one pass.** Before moving, grep the repo for BOTH the full
  path and the bare filename; rewrite every hit (index line, LESSONS, ADRs, other reports) to the
  `done/` path in the same commit. A move that breaks one citation is worse than the clutter —
  this sweep is the ONE sanctioned exception to §10.40's "never moved", and the rewrite is what
  keeps the exception honest. Evidence subfolders (`<task>_<what>/`) move with their report.
- **Stays in the index, same section.** The `[x] closed` line keeps its status and history; only its
  file path gains `done/`. Throughput counting is untouched — done/ is INSIDE the author's folder.
- Same write authority as every shared-file transition: the ORCHESTRATOR/owner sweeps; workers never
  move files out of their own delivered set (§10.42).

## 5. Lint the memory set (drift check)
- **Strip noise:** delete VCS/ritual bookkeeping ("pushed N commits", sha ranges, "ran /keel-distill")
  and conversational meta ("user asked if I saved", "don't rush") from HANDOVER — it's git-log /
  ritual-log-derivable, and it's usually what pushed the file over cap (keep decisions + their WHY).
- **Header hygiene (every memory file, not just HANDOVER).** A header is DOCTRINE — how the file
  works, written once, frozen. Move OUT anything that is state: a date or changelog line, a
  measurement ("file is 202 lines"), a debt or pending decision (nobody triages a header, so it
  becomes a permanent complaint — send it to `## Discovered`, then a `## Next` item with a
  done-when), a cap NUMBER (write "cap: `.claude/keel-caps`" — a copy drifts from the file that sets
  it, which is why the stale-cap-header lint below exists), a chat quote. Also collapse teaching
  prose that merely restates `rules.md`: it is paid in every session by an `@`-imported file and the
  two wordings drift — the detail lives in `docs/memory-files.md`. What EARNS a header line is a
  timeless, non-obvious invariant (field example: *"this file is `@`-imported IN FULL — a lane
  heading is a WRITE boundary, not a context boundary"*). Measured on the template itself: the three
  imported files carried 110 header lines, 55 after this rule. (The SessionStart hook flags dated
  lines and hard-coded caps in a header.)
- Contradictions between `rules.md` / `LESSONS.md` / `CLAUDE.md` — flag, ask the user which wins.
- **Decision/constraint drift (`docs/adr/` + `.claude/rules/`):** an *Accepted* ADR contradicted by a
  newer decision, a measurement, or the code as it now stands → PROPOSE `Superseded (by ...)` — the
  OWNER flips the status, never this ritual; a path-scoped rule whose constraint has been overtaken
  → propose rewrite or retirement the same way. Also verify each rule's/skill's `paths:` globs still
  match existing files (a glob matching nothing = the rule silently never loads — a dead rule; brace
  expansions past the documented 1,000-pattern budget and malformed `[` brackets ALSO match nothing,
  silently), and the ADR README index still mirrors the folder.
- **LESSONS `## Index` router mirror:** every Index line's target file exists, and every
  graduated-lesson rule/skill/doc has its ONE Index line — an orphan cluster is invisible to
  sessions whose trigger hasn't fired; a dead line hides lessons that still exist. (The reground
  hook flags dead targets at session start; the missing-line direction is checked here.) Same mirror check for `reports/team/README.md`: every
  INDEXED report — live status, or cited by a permanent record (the template's scope line) — has
  exactly ONE index line (an orphan = unfindable evidence; a duplicate diverges —
  field case: the same report indexed twice with two different status texts), statuses use only
  the controlled vocabulary (`wip · delivered · verified — owner part: <…> · closed <date>
  accepted|rejected`, `[x]` only at closed), and the mirror counts `done/` files too — a `closed`
  line whose path lacks `done/` is a §4 sweep candidate, a non-closed line pointing INTO `done/`
  is a bug.
- Stale claims (files/commands/paths that no longer exist) — fix or mark superseded. Resolve bare
  BASENAMES against the tree before flagging: field measurement found ~54% of citations are
  basename-only and DO resolve — a naive path check reports them as false staleness.
- **Language drift (rules §9.31):** HANDOVER/LESSONS/worker boards are ENGLISH on every project.
  Convert only the lines this run already rewrites/merges/rotates (gradual, no bulk-translation pass:
  a mass rewrite risks meaning loss and buries the real diff) — quoted user wording stays as-is.
- Stale cap HEADERS in the memory files themselves (e.g. a LESSONS.md header still quoting an old
  "~100"): correct to the current thresholds below — headers are prose, the SessionStart hook is the
  authority; they drift in adopted projects because `/keel-update` never touches PROTECTED memory files.
- Cap check (solo defaults — the project's `.claude/keel-caps` overrides them, rules §10.40):
  `HANDOVER.md` ≤ ~150 lines, `LESSONS.md` ≤ ~250, `TASKS.md` ≤ ~100, `CLAUDE.md` ≤ ~200,
  `rules.md` ≤ ~400 — of which the stock template is what `wc -l rules.md` says on a fresh clone,
  so the project's own rules get the REMAINDER (rule budget §10.38 — measure it, never copy a number;
  merge/retire/promote to a hook, don't just append). Every file also has a KB cap (`<FILE>_KB`).

## 6. Report → approve → commit
Summarize: N blocks archived, M lessons added/merged/superseded/promoted, lint findings. On approval,
apply + propose a commit (rules.md §6.15). Never push without user approval.