agentleFS
armenrarmenr/modelmux/.claude/skills/distill-lessons/SKILL.md

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

  • Other versions1 project uses a version of this.

    Word for word · 0

    None found.

    Edited · 0

    None found.

    Wrote their own version · 1

    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.

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
  1. Distinctive:

    Run after a meaningful chunk of work (a commit, an ADR write, a design discussion, a failed-then-fixed pattern) to extract candidate …

    line 12
  2. Distinctive:

    If you can't identify any candidate meeting all four, that's a fine answer.

    line 74
  3. Very specific:

    Default severity: low. Reserve high for could-have-been-production-critical.

    line 88
  4. Very specific:

    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 …

    line 92
  5. Distinctive:

    If N=0: "/distill-lessons reviewed the last 50 journal entries.

    line 102
  6. Distinctive:

    After a work session that surfaced something future-you would benefit from remembering.

    line 109
  7. Distinctive:

    After a failed-then-fixed pattern (these almost always make good lessons).

    line 110
  8. Distinctive:

    After running a runbook procedure for the first time (the gaps you hit on first run are the lesson).

    line 111
  9. Very specific:

    Do NOT inflate severity: Default low; high = could-have-been / was production-critical.

    line 117

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.