Distill Session Knowledge Agent Skill

distill-session-knowledge

Offline miner. Turns past pi session traces into durable artifacts. No new

infrastructure — routes into skill_manage, the memory tool, and docs/

(indexed by context-mode FTS5). Dry-run by default; nothing is written until you

review the plan and explicitly apply.

Engine: the published @blackbelt-technology/pi-dashboard-session-distiller

package, invoked through its distill-session-knowledge bin (this skill package

declares it as a runtime dependency).

When to use

• "Mine / distill my pi sessions", "what recurring mistakes do I keep making",

"extract reusable procedures from my history", "turn session logs into skills".

• After a stretch of work, to harvest verified lessons before they decay.

Procedure

• Dry-run the miner (no writes) for this project:

   npx --no distill-session-knowledge --cwd "$(git rev-parse --show-toplevel)"

Add --n <k> to change the recurrence threshold (default 3). Add --json to

emit the full routing plan as JSON for programmatic review.

• Review the routing plan. Each entry shows signal -> sink [action] conf=…:
• procedure -> skill_manage — candidate reusable SKILL.md.
• fault -> memory(failure/tool-quirk) — a wrong-way→right-way tool fix.
• user_correction -> memory(failure/correction) — +AGENTS.md flag means it

establishes a rule and should also patch the relevant AGENTS.md row.

• ask_user_decision -> memory(project/convention) — a recorded human decision.
• documentation -> docs — a recurring how-to summary.
• STALE flag = confidence below floor; skip or prune, do not write.

• Apply once the plan looks right — persists the watermark + below-threshold

candidates store and prints the final plan:

   npx --no distill-session-knowledge --cwd "$(git rev-parse --show-toplevel)" --apply --json

• Execute the routed writes from the plan, using your tools (this is the

haiku-class subagent distillation step). For each non-stale entry:

• skill_manage → mcp__pi__skill_manage create/patch (query existing first).
• memory → mcp__pi__memory add with the entry's target + category

(memory_search first to dedup; merge into a match instead of duplicating).

• docs → delegate the write to a docs subagent in caveman style per the

Documentation Update Protocol, then ctx_index the new doc so it is

FTS5-searchable (task 5.2).

• +AGENTS.md entries → patch the relevant AGENTS.md rule via the docs subagent

(≤200 chars/row, caveman style) in addition to the memory write.

Guardrails

• Dedup before every write — re-running over the same corpus must create zero

duplicates (the planner marks merge when a sink already holds the artifact;

still query the live sink, the planner's exists is conservative).

• Never write a STALE artifact.
• Stay within this project's sessions (the miner already scopes to the cwd dir).
• Respect the doc protocol: main agent orchestrates, a subagent writes under docs/.

Verification

• npx --no distill-session-knowledge --cwd "$(pwd)" prints a routing plan and

mutates nothing (dry-run default; no watermark advance).

• Re-running the dry-run over the same corpus yields the same plan (idempotent).
• After apply + routed writes, ctx_search returns a freshly distilled doc.