Distill

---
name: distill
description: "Knowledge distillation methodology: candidate extraction, confidence scoring, tier routing, conversation-scoped mode. TRIGGER when: running /learn or /distill, deciding if an insight is memory-worthy, or scoring a knowledge candidate. SKIP: ad-hoc memory reads/writes (use agent-memory); vector storage (use semantic-memory-store)."
---

# 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

| Target | When | Path |
|--------|------|------|
| `shared` | Cross-cutting insight useful to all agents | `.scaffolding/agent-memory/shared/KNOWLEDGE.md` |
| `agent:{name}` | Domain-specific to one agent | `.scaffolding/agent-memory/agents/{name}/MEMORY.md` |
| Overflow | KNOWLEDGE.md would exceed 200 lines | Route to 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 (auto-injected into every agent context). 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`):

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

Apply the Knowledge Candidate Criteria and Confidence Scoring above against these
two 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.

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