| name | distill-lessons |
| description | Surface candidate lessons (or near-misses) from recent log.md journal entries + session activity — scanning for false-beliefs, over-generalizations, staleness, tool-failures, and near-misses. Writes proposals to .agent-docs/now/lessons/proposals.md for two-step human-gated promotion (maturity seedling→budding→evergreen; provenance llm-draft→llm-reviewed). Use after a failed-then-fixed pattern, a surprising discovery, a runbook's first run, or as part of /handoff. |
| provenance | kit-template |
| created | "2026-07-03T00:00:00.000Z" |
| last-modified | "2026-07-03T00:00:00.000Z" |
| allowed-tools | Bash(tail:*), Bash(cat:*), Bash(grep:*), Bash(git log:*), Read, Write, Edit |
/distill-lessons — surface candidate ledger entries
Run after a meaningful chunk of work (a commit, an ADR write, a design discussion, a
failed-then-fixed pattern) to extract candidate entries for the append-only lessons ledger. Output
goes to .agent-docs/now/lessons/proposals.md — promotion to .agent-docs/lessons/<slug>.md is
human-gated (a load-bearing discipline; if you formalize it, record it as an ADR). This skill NEVER
writes into lessons/ directly.
Foreground in the main agent. Context-capture skills don't background cleanly (same reasoning as
/flush): the session state they read from is the live conversation.
Recent journal entries (last 50)
!tail -50 .agent-docs/log.md 2>/dev/null || echo "(no log.md yet)"
Existing Tier-1 lessons MOC (for the dedup check)
@.agent-docs/now/lessons/MOC.md
Existing proposals (don't duplicate)
@.agent-docs/now/lessons/proposals.md
Steps
1. Review the inputs above
The shell-interpolated tail -50 gives you the fresh journal. The @-imports show what's already in
the Tier-1 MOC and staged as a proposal — that is your dedup baseline. If a candidate is already
covered by a MOC row or an existing proposal, skip it.
2. Scan the session for the five candidate TYPES
Walk the recent work through each lens (the type: axis of templates/lesson-template.md). Most
sessions surface zero to a few — that is fine:
- false-belief — you (or an agent) acted on something that turned out not to be true. "I assumed
X; the tree/tool/docs said Y." The correction is the lesson.
- over-generalization — a rule or pattern applied where it didn't hold; the boundary condition
you hit is the lesson.
- staleness — a fact, version, or path that was right once and has drifted; what you now trust
instead, and how you'd detect the drift next time.
- tool-failure — a tool/command/agent that failed, misreported, or needed a workaround; the
reliable path forward.
- near-miss — something expensive almost happened and a specific save caught it; the
reliable-save is the lesson (not the luck).
3. Keep only candidates that meet ALL of the bar
For each candidate, verify it meets all of:
- Concrete trigger — one sentence naming the condition that fires this lesson (the paths,
commands, or error signatures that say "this is happening now").
- Stable claim with consequence-rationale shape — "When X, do Y because Z" (lesson), or "X almost
happened; Z saved us; the reliable-save is Y" (near-miss).
- Evidence link — a
log.md timestamp / commit SHA / ADR-NNNN / INC-NNN — REQUIRED to
promote past the seedling stage.
- Not a duplicate — neither the slug nor the underlying claim appears in the MOC or
proposals.md.
If you can't identify any candidate meeting all four, that's a fine answer. Don't lower the bar —
better zero high-quality proposals than three weak ones.
4. For each surviving candidate, append a draft proposal
Append to .agent-docs/now/lessons/proposals.md (NOT to lessons/). Use the
templates/lesson-template.md schema. This skill always writes provenance: llm-draft and
maturity: seedling — the two-step promotion is somebody else's gate, not yours:
- Axis 1 — maturity:
seedling → budding (applied at least once) → evergreen (recurred 3+; earns
a Tier-1 MOC row). You only ever emit seedling.
- Axis 2 — provenance:
llm-draft → llm-reviewed (operator signs off on the claim) → human
(substantially rewritten). You only ever emit llm-draft.
Default severity: low. Reserve high for could-have-been-production-critical. For a near-miss, keep
the near-miss body variant (## What almost happened / ## What made the save reliable /
## Recurrence count) and delete the plain-lesson sections.
Possible MOC row. If a candidate's claim already looks like it has recurred 3+ times (you can see
the repetitions in the journal), note in the proposal body that it is an evergreen candidate — a row
for now/lessons/MOC.md. Do not add the MOC row yourself; flag it for the human gate.
5. Surface to the user
- "/distill-lessons surfaced N candidates → written to
.agent-docs/now/lessons/proposals.md"
- One line per candidate: its
type + its claim.
- "Review at the next /handoff for accept / defer / reject (and any promotion)."
If N=0: "/distill-lessons reviewed the last 50 journal entries; no candidates meet the promotion
criteria right now."
When to invoke
- After a work session that surfaced something future-you would benefit from remembering.
- After a failed-then-fixed pattern (these almost always make good lessons).
- After running a runbook procedure for the first time (the gaps you hit on first run are the lesson).
- Periodically as part of
/handoff (which can call this internally — but standalone is fine).
Anti-patterns
- Do NOT promote directly to
.agent-docs/lessons/. Proposals only. The human gate is the point.
- Do NOT inflate severity. Default
low; high = could-have-been / was production-critical.
- Do NOT write lessons that are really runbooks (a procedure →
runbooks/) or really ADRs (a
decision with alternatives → decisions/). A lesson = observed pattern + mitigation.
- Do NOT include secrets, credentials, or regulated / user data — reference a path, never a value.
Design rationale
The lessons ledger is the LP-NNN spine (CONVENTIONS.md §4) with the three-axis front-matter
(provenance × maturity × severity) and the five type discriminators (templates/lesson-template.md).
Human-gated promotion exists because an unreviewed auto-promoted "lesson" is as likely to encode a
one-off accident as a durable pattern — the review is what separates the two. Fresh journal content is
pulled at invocation via the shell-interpolation block above, so the skill always sees current reality
rather than a stale snapshot.
