distill

/distill

Distill agent instruction files into structured imperatives, compose with policy algebra, and visualize the rule system. Three-stage pipeline.

Usage

/distill                                    # full pipeline on default files
/distill ai-workspace/rules/*.md            # specific targets
/distill --stage imperatives                # run only extraction
/distill --stage compose                    # run only policy algebra (requires prior extraction)
/distill --stage visualize                  # run only visualization (requires prior composition)

Pipeline

  ┌─────────────┐     ┌──────────────┐     ┌─────────────┐
  │ /imperatives │────▶│/policy-algebra│────▶│ /visualize  │
  │  extract     │     │  compose     │     │  render     │
  └─────────────┘     └──────────────┘     └─────────────┘
        │                    │                    │
    JSONL file         Starlark block      Mermaid diagrams

Stage 1 — Extract (/imperatives)

1. Invoke /imperatives with the target files (or defaults: ai-workspace/rules/*.md + AGENTS.md).
2. Save output to ai-workspace/research/<name>-imperatives.jsonl.
3. Present the summary (count, level breakdown, scope breakdown).

Ask the user: "Review the extraction before composing? (y/continue)"

• If yes: present the JSONL for review, wait for feedback, re-extract if needed.
• If continue: proceed to Stage 2.

Stage 2 — Compose (/policy-algebra)

1. Project the JSONL to natural-language bullets: <level>[ NOT] <subject> <predicate>[ when <when>] — one bullet per imperative.
2. Invoke /policy-algebra with the projected bullets.
3. Save the Starlark composition to ai-workspace/research/<name>-policy.md.
4. Present the surfaced structure (decision functions, branching points).

Stage 3 — Visualize (/visualize)

1. For each major decision function in the Starlark output, invoke /visualize.
2. Content shape is typically graph (decision trees) → Mermaid flowcharts.
3. Append diagrams to the policy doc.

Naming

The <name> slug defaults to the current date + "distill" (e.g., 2026-05-04-distill). Override with --name <slug>.

Output

All artifacts land in ai-workspace/research/:

• <name>-imperatives.jsonl — structured extraction
• <name>-policy.md — Starlark composition + diagrams

Failure modes

Condition	Behavior
/imperatives finds zero imperatives	Report and stop. No point composing empty input.
/policy-algebra unavailable	Skip Stage 2, warn. Stage 3 can still visualize the JSONL directly.
User interrupts between stages	Artifacts from completed stages are preserved. Resume with --stage.

When to use

• AGENTS.md or rules/ grew past a size threshold and needs trimming
• Before a major restructuring of agent instruction files
• To audit what rules actually exist vs what you think exists
• As input to a plan that modifies the rule system