distill - SKILL.md Agent Skill

name: distill description: Mines the conversation logs (logs/conversations/) for signal the context files missed — facts that never got captured, recurring topics with no home, repeated questions, and usage patterns. The sanctioned exception to the "logs are write-only" rule. Use when user says "/distill", "mine the logs", "what have we been talking about", or quarterly as maintenance. argument-hint: [--since=YYYY-MM-DD] [--report-only]

The repo logs every conversation to `logs/conversations/` "for future model analysis" — this skill is that analysis. Read the accumulated JSONL logs, compare what was *discussed* against what was *captured* in context files, and surface: missed memory updates, recurring themes that deserve a domain or skill, questions asked repeatedly (= retrieval gaps), and how the system is actually being used. Output a report and (with approval) apply the fixes. The repo learning from its own usage. `/distill` — Mine logs since the last distill run, report findings, offer to apply fixes `/distill --since=2026-03-01` — Explicit window `/distill --report-only` — Findings only, no context changes ## 1. Determine the Window

Read projects/ai-assistant/context.md → "Distill Log" section for the last run date. Default window: last run → today (first run: everything). --since overrides.

2. Read the Logs

find logs/conversations -name "*.jsonl" -newermt "{window start}" | sort

This is the sanctioned exception to the write-only rule in protocols/conversation-logging.md. Read in batches; for large windows, fan out parallel Explore agents by month and merge their findings — each agent gets the same extraction brief (step 3) and returns structured findings, not transcripts.

3. Extract Signal

For each conversation, note topic + domain, then look for:

Missed captures — specific facts, preferences, decisions, or numbers stated in conversation that never landed in any context/reference file (verify by grepping the repo for the fact). These are memory-protocol failures — the highest-value finding.
Recurring topics without a home — subjects appearing in 3+ sessions that map to no domain/subdomain (candidate new domain) or repeatedly straddle two domains awkwardly (candidate matrix entry).
Repeated questions — the same question answered from scratch in multiple sessions = a retrieval gap. Fix is usually a reference.md section or a skill.
Stale-pattern signals — domains discussed often but whose context.md rarely updated (capture discipline gap), or skills that exist but never get invoked in the logs (awareness gap — like track-feed/log-expense going unused for weeks after being built).
Usage shape — which domains dominate, cadence, session types. One short paragraph, not a dashboard.

Ignore: pleasantries, one-off lookups that resolved fine, anything already correctly captured.

4. Report

# Distill Report — {date} (window: {start} → {end}, {N} conversations)

## Missed captures (apply these)
- **{domain}**: "{fact}" — said {date}, absent from {expected file}

## Recurring topics without a home
- {topic} — {N} sessions — suggest: {new subdomain / matrix entry / reference section}

## Repeated questions (retrieval gaps)
- "{question}" — asked {N}× — suggest: {reference.md section / skill}

## System observations
{capture-discipline gaps, unused skills, usage shape — short}

## Proposed actions
1. ...

5. Apply (unless --report-only)

Walk the proposed actions with the user — apply approved ones to the relevant context/reference files (normal memory protocol). Don't bulk-apply without a look.

6. Record the Run

Append to projects/ai-assistant/context.md → "Distill Log": date, window, conversations read, findings applied/skipped. This is also the next run's window anchor.

- **First run** (no Distill Log): read everything; cap the report at the ~10 highest-value findings rather than an exhaustive dump - **Huge window**: fan out by month with parallel agents; merge findings; dedupe - **A "missed capture" was deliberately not captured** (sensitive, one-off): skip silently when context makes that obvious; ask when unsure - **Logs contain corrections of earlier statements**: the later statement wins — check the fact's final state across the window before flagging - **Nothing found**: say so briefly — "logs and context are in sync" is a valid, good outcome. Don't manufacture findings 1. Window anchored on the last run (Distill Log) and recorded after this one 2. Every "missed capture" verified absent from the repo before flagging (grep, don't assume) 3. Findings are specific (file + suggested edit), not vibes 4. User approves before context changes; --report-only makes none 5. Logs remain untouched — this skill only ever reads them