Distill

Distill

Compress a complex system into the smallest useful set of abstractions that still reconstructs its behavior.

Read references/input-strategies.md when starting on a codebase, research paper, transcript, or article — it has input-type-specific starting heuristics.

Core Concepts

Primitives: the irreducible building blocks that can't be decomposed further without losing essential behavior. A good primitive set is:

• Complete — you can reconstruct the full system's behavior from just these pieces
• Orthogonal — each primitive captures something the others don't
• Minimal — removing any one primitive loses something essential
• Sized independently — don't force primitives to the same level of abstraction when one is genuinely bigger than the others
• Use as many primitives as reconstruction requires; treat a large set as a signal to try another compression pass, not an automatic failure.

Distillation vs. summarization: summarization preserves information at lower fidelity. Distillation re-expresses the essence in a new, cleaner form, which is often more useful than the original because it strips away accidental complexity. For example, "uses PostgreSQL" is implementation; "needs durable ordered storage" is essence.

Accidental vs. essential complexity (per Fred Brooks): essential complexity is inherent to the problem. Accidental complexity comes from the implementation. Distillation separates them.

Workflow

Two phases, Orient and Compress, iterate until the user is satisfied with the decomposition.

Phase 1: Orient

Before proposing a decomposition, identify what the user needs to do with it and which layer matters. Ask one question at a time only when the answer changes the primitive set.

Skip straight to Phase 2 when the user's intent is already obvious from context or for one-shot asks. Ask again only if the intended layer or use of the distillation is unclear enough to change the primitive set.

Phase 2: Compress

Each turn follows this pattern:

Step 1 — Propose primitives. Present a candidate decomposition (format depends on context; see Output Formats), always including:

1. The primitive set — named, with a one-sentence description of each
2. Proposed granularity — how many primitives, and why this number
3. What was discarded as accidental complexity
4. Confidence flags — where you're least sure about the decomposition

Step 2 — Invite pushback. Ask the user to challenge the decomposition rather than presenting it as final — surface where it might be wrong, not just whether it's acceptable.

Step 3 — Refine. Based on feedback, propose a revised decomposition, showing what changed and why. Repeat until the user says it feels right. For one-shot asks, stop after a candidate decomposition that is complete, orthogonal, minimal, and annotated with confidence flags.

Convergence Signals

You're done when:

• The user confirms the primitive set matches their intuition
• Each primitive feels irreducible — you can't merge or remove any
• The user can explain the system to someone using only these primitives
• (For code) you could sketch a minimal implementation from just the primitive set

Output Formats

Choose based on what the user needs; ask when in doubt.

• Conceptual Map (the default; use it for any input unless a format below is requested or its trigger fires) — primitives, relationships, reconstruction, discarded accidental complexity, and confidence flags.

• Minimal Implementation (only when requested or explicitly useful) — a set of files (like Karpathy's 3 files) that capture the essential behavior: actually runnable, named to reflect the primitives, stripped of accidental complexity, commented to map each piece back to the original.

• Behavioral Spec (when the user wants a SKILL.md or similar) — captures what the system does without prescribing how; useful when the distillation will guide an agent or a rewrite.

• Hybrid — combine formats for complex systems, e.g. a conceptual map plus a minimal implementation, or a behavioral spec with a reference implementation.

• HTML Map (only when requested, or spatial comparison is the deliverable) — a self-contained HTML artifact with primitive cards, relationship arrows, confidence flags, and a discarded-as-accidental section. Good fit for codebase maps, architecture primitives, research-paper concept graphs, and multi-document synthesis. Keep names and reconstruction concise enough to read in one pass.