/distill

name: distill
description: "Knowledge distillation: candidate extraction, confidence scoring, tier routing. Invoked by /learn and the memory-ingest Stop hook, not loaded proactively by agents. TRIGGER when: /learn or the Stop hook asks to distill, or scoring a candidate. SKIP: file memory writes (use agent-memory); vector store (use semantic-memory-mcp)."

Distill Methodology

Guidelines for automated knowledge extraction and consolidation across memory systems.

Knowledge Candidate Criteria

An insight qualifies as a knowledge candidate when it meets ANY of these:

| Criterion | Source | Example | |-----------|--------|---------| | Cross-conversation pattern | 3+ context.md files contain the same insight | "Redis pool exhaustion under SSE load" | | Architectural decision | design.md contains explicit Decision/Rationale section | "Use pgvector for semantic search" | | Recurring gotcha/bug | Keyword match in specs: gotcha, bug, pattern, lesson | "POST 301 redirect strips body" | | Stale reference | File path in memory points to non-existent file | "app/backend/old_module.py" | | Cross-tier duplicate | Same entry in both KNOWLEDGE.md and agent MEMORY.md | Duplicated bullet point |

Confidence Scoring

| Occurrences | Confidence | Tier Recommendation | |-------------|------------|---------------------| | 5+ conversations | 0.5 - 1.0 | shared (KNOWLEDGE.md) | | 3-4 conversations | 0.3 - 0.5 | shared (with review) | | 1-2 conversations | 0.1 - 0.2 | agent-specific MEMORY.md | | Decision section | 0.7 fixed | shared | | Pattern keyword | 0.5 fixed | shared | | Stale reference | 0.9 fixed | cleanup action |

Auto-store threshold: candidates scoring **>= 0.8** are auto-stored to the vector store (silent, cold layer) via `semantic_store` — see the memory-ingest Stop hook. This is the single source of truth for that threshold.

Tier Routing

Tier paths and what belongs in each are defined in the `agent-memory` skill (§ Memory Tiers) -- do not restate them here. Route `shared` candidates to `KNOWLEDGE.md` and `agent:{name}` candidates to that agent's `MEMORY.md`.

**Overflow:** if `KNOWLEDGE.md` would exceed 200 lines, route the candidate to the most relevant agent file.

Output Format

Candidates are structured as:

- content: The knowledge text (max 500 chars)
- source: File path or "conversations:N_occurrences"
- source_type: conversation | spec | memory | semantic
- confidence: 0.0-1.0
- target_tier: shared | agent:{name}
- tags: categorization tags

200-Line Limit Enforcement

KNOWLEDGE.md has a hard limit of 200 lines (read in full by agents). When merging would exceed this limit:

1. High-confidence candidates (>= 0.7) get priority 2. Lower-confidence candidates overflow to agent-specific files 3. The orchestrator routes overflow to the most relevant agent based on tags

Dry-Run vs Apply

• **Dry-run** (default): Report what would change, write nothing
• **Apply**: Create timestamped backup, then write merged content
• **Restore**: Revert files from any backup timestamp

Conversation-Scoped Distillation

The `/learn` command runs distillation against a **single conversation** rather than mining all of `.scaffolding/conversations/`. This mode is backend-free and self-contained — no session-log mining, no database.

Inputs for one `conversation_id` (a UUID `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`). `.scaffolding/conversations/` is a symlink to `<share>/projects/<repo-name>/conversations`; paths are unchanged:

| Input | Path | Role | |-------|------|------| | Conversation memory | `.scaffolding/conversations/{id}/agent-memory/context.md` | Decisions and findings recorded during the chain | | Design decisions | `.scaffolding/conversations/{id}/specs/design.md` (`## Decisions` section, if present) | Architectural choices + rationale | | Action timeline | `.scaffolding/conversations/{id}/timeline.md` (if present) | Deterministic, metadata-only per-run record (files edited, commands, errors, repeated failures). Never contains raw tool output |

Apply the Knowledge Candidate Criteria and Confidence Scoring above against these files only. With a single conversation, the "Cross-conversation pattern" criterion does not apply; rely on the Decision-section and pattern-keyword criteria. If `context.md` is absent, there is nothing to distill — exit cleanly.

**Repeated failures (from `timeline.md`).** A line under `repeated failures` (the same tool + normalized target failed >= 2 times in a run) becomes a *gotcha* candidate with a **fixed confidence of 0.5**. At 0.5 it is below the 0.8 auto-store threshold, so it goes to `.scaffolding/.ingest-queue` / `/learn` for propose-then-confirm and is NEVER auto-stored. Describe the failing command or tool and the count only; the timeline holds no output, so do not invent a cause.

Skill Promotion Criterion

Each distilled candidate routes to one of two destinations:

| Candidate shape | Destination | Decision rule | |-----------------|-------------|---------------| | Situational insight, gotcha, or one-off decision | Memory entry — `shared`, `agent:{name}`, or conversation tier per the Tier Routing rules above | The knowledge is a *fact about this codebase*. | | Repeatable procedure or methodology | New skill — propose a `/create-skill` invocation with a pre-filled draft | The knowledge is a *reusable how-to* an agent would follow on future, unrelated tasks. |

Promote to a skill only when the candidate is a generalizable procedure, not a single fact. A one-off fact ("module X has a 301 redirect bug") is a memory entry; a recurring procedure ("how to safely roll a zero-downtime migration") is a skill. When in doubt, prefer a memory entry — skills carry an auto-invocation cost and should stay few and sharp.