distill-lessons
Skill2 starsChanged 4 months agoMITView on GitHub
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.
1 other project uses a version of this.
Adopted by
Most recently taken up by
- braincandy-parallel/tamarindos-workflow-kittheir own version, first seen Sep 18, 2026
Other versions1 project uses a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 1
- braincandy-parallel/tamarindos-workflow-kit★ 0same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository11 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- debriefSkill
- explain-modelmuxSkill
- flushSkill
- getting-startedSkill
- handoffSkill
- kit-doctorSkill
- kit-upgradeSkill
- orientSkill
- sitrepSkill
- switch-modelsSkill
The file
We split this skill into the rules it gives an agent
9 rules. About 0 are common, 6 are distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈6
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 12
Run after a meaningful chunk of work (a commit, an ADR write, a design discussion, a failed-then-fixed pattern) to extract candidate …
- Distinctive: line 74
If you can't identify any candidate meeting all four, that's a fine answer.
- Very specific: line 88
Default severity: low. Reserve high for could-have-been-production-critical.
- Very specific: line 92
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 …
- Distinctive: line 102
If N=0: "/distill-lessons reviewed the last 50 journal entries.
- Distinctive: line 109
After a work session that surfaced something future-you would benefit from remembering.
- Distinctive: line 110
After a failed-then-fixed pattern (these almost always make good lessons).
- Distinctive: line 111
After running a runbook procedure for the first time (the gaps you hit on first run are the lesson).
- Very specific: line 117
Do NOT inflate severity: Default low; high = could-have-been / was production-critical.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
/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.mdtimestamp / commit SHA /ADR-NNNN/INC-NNN— REQUIRED to promote past theseedlingstage. - 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 emitseedling. - Axis 2 — provenance:
llm-draft→llm-reviewed(operator signs off on the claim) →human(substantially rewritten). You only ever emitllm-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.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

