session-distill

Session Distill

Turn session learnings into guidance that makes future runs faster and cheaper. The value is NOT documenting what worked — it is documenting the dead ends, so the next agent never walks into them.

Step 1 — Harvest candidates

Mine three sources: the current conversation, LESSONS_LEARNED.md, and Beads task notes (bd show <id> --json for tasks touched this session). A candidate is:

• A solution that worked AFTER one or more failed attempts (the highest-value kind).
• A non-obvious environment/API fact that was verified in-session (command output, file read, passing test).
• A decision between approaches, with the rationale that settled it.

For each candidate, record: problem → attempts that failed and WHY each failed → final solution → root cause → the evidence (the exact command/output or file:line that confirmed it).

Epistemic gate (hard rule): only distill solutions with observed evidence in the session. "The error went away" without a derived cause is not distillable — the fix may have been the cache clear next to it. If the solution was merely the last thing tried, say so and skip it; fossilizing a superstition into permanent guidance poisons every future session. When in doubt, re-verify now (run the command, revert-and-retry) before distilling.

Step 2 — Classify

Tag each candidate on two axes:

• Failure type — use the taxonomy in the lessons-learned rule (CONFABULATION, ASSUMPTION_ERROR, KNOWLEDGE_GAP, STALE_KNOWLEDGE, ENVIRONMENT_QUIRK).
• Scope — PROJECT (paths, versions, quirks of THIS codebase: "this theme's build needs X") vs UNIVERSAL (true in any Drupal/DDEV project: "lazy builder args must be scalars").

Step 3 — Route to the right destination

Check for an existing home FIRST — grep the skills/rules for the topic before writing anything new:

# Covers both tools' synced copies plus the project's own skills/rules:
grep -rli "KEYWORD" ~/.claude/skills/ ~/.claude/rules/ \
  ~/.config/opencode/skills/ ~/.config/opencode/rules/ \
  .claude/skills/ .claude/rules/ 2>/dev/null