distillation

name	distillation
classification	passive
description	Extract high-signal patterns from the napkin into a curated distilled.md rulebook. Triggered when the napkin exceeds ~500 lines. Handles archival, deduplication, and rotation.

Distillation

Extract actionable rules, patterns, and troubleshooting from the session napkin into a compact, curated reference. This skill complements the napkin skill.

Trigger: When .agent/memory/active/napkin.md exceeds ~500 lines, or when the user requests distillation.

File Layout

.agent/memory/
  active/
    distilled.md                  # Curated rulebook (read every session)
    napkin.md                     # Current session log
    archive/
    napkin-YYYY-MM-DD.md          # Archived napkins (historical reference)

Distillation Protocol

1. Extract

Read every "Patterns to Remember", "Mistakes Made", "Key Insight", and "Lessons" section from the outgoing napkin. Collect all entries that would change behaviour if read next session.

2. Merge

Compare extracted entries against existing active/distilled.md. For each entry:

• New insight: Add it to the appropriate section.
• Duplicate of existing rule: Skip it — the rule is already captured.
• Refinement of existing rule: Update the existing entry with the sharper formulation.
• Contradiction: Investigate. The more recent finding usually wins, but verify before overwriting.

3. Extract and Prune

The primary mechanism for keeping distilled.md within size constraints is extracting established concepts to permanent documentation (directives, READMEs), then removing the entry. Permanent docs are discoverable without specialist knowledge; active/distilled.md is a specialist refinement flow and should hold only what has NOT yet matured into settled practice.

For each entry, ask: has this pattern become established enough to belong in a permanent doc? If so, create the permanent doc first, then remove the distilled entry. Common destinations:

• Rules codified in .agent/directives/principles.md
• Example-specific patterns documented in .agent/examples/
• Tooling documented in project READMEs
• Meta-principles about the Practice itself in .agent/practice-core/practice-lineage.md

Also remove entries that are already captured in existing permanent documentation — no duplication across the two tiers.

4. Archive

Move the outgoing napkin to the archive:

cp .agent/memory/active/napkin.md \
   .agent/memory/active/archive/napkin-YYYY-MM-DD.md

Use the current date for the filename.

5. Start Fresh

Create a new .agent/memory/active/napkin.md with a session heading documenting the distillation itself.

active/distilled.md Structure

Target: under 200 lines of high-signal content. Every entry earns its place by being actionable.

# Distilled Learnings

## User Preferences
## Python
## Demo Surface
## Testing
## Architecture
## Troubleshooting

Adapt sections to the repo's domain. Add or remove sections as the project evolves. The structure should make it easy to find what you need quickly.

Quality Criteria

A good active/distilled.md entry is:

• Specific: "Inject chart output through a callable in CLI tests" not "charts are awkward"
• Actionable: tells you what to DO, not just what happened
• Non-obvious: captures something you would not know from reading the code
• Terse: one to two lines maximum per entry

A good active/distilled.md overall is:

• Under 200 lines
• Zero redundancy with permanent documentation
• Readable in under 2 minutes
• Updated after every distillation, not between them

When NOT to Distil

• Do not distil mid-session — the napkin is a working document during active work
• Do not distil if the napkin is under 400 lines — there is not enough content to justify the overhead
• Do not distil "What Was Done" sections — those are session history, not learnings