Use this skill when $wisdom distill is invoked directly or when the Stop hook queues a background distillation request.
Objective
Extract durable, reusable lessons from a completed, exited, or failed session and route them into CocoWisdom without blocking the developer's next turn.
Inputs
- Optional session or run id from
$wisdom distill <id>. .cocoplus/wisdom/SCHEMA.mdwhen present..cocoplus/session/PROGRESS.md,.cocoplus/session/CONTEXT.md,.cocoplus/session/steps.jsonl, and relevant lifecycle artifacts..cocoplus/wisdom/review-queue.mdfor unresolved contradictions.
Procedure
- Check
.cocoplus/wisdom/SCHEMA.md. If it does not exist, create a minimal schema with topic categories, source session id, outcome status, evidence pointer, confidence, contradiction handling fields, and an optional## Stage Mappingstable for routing stage role patterns to positive wisdom topics. - Read only the terminal-session artifacts needed to identify lessons, rejections, corrections, governance decisions, and repeated failure modes.
- Classify each candidate into a schema-declared category file. Do not invent standing-context text outside the schema.
- If a candidate contradicts existing wisdom, follow
[wisdom].contradiction_action:queue: add it to.cocoplus/wisdom/review-queue.md.skip: record the skipped contradiction in the report.overwrite: replace only when the evidence pointer and rationale are explicit.
- Write accepted entries to the matching topic file under
.cocoplus/wisdom/. - Write a distillation report to
.cocoplus/lifecycle/cocoflow/<run-id>/distillation-<timestamp>.jsonwhen a run id exists, otherwise.cocoplus/wisdom/distillation-<timestamp>.json.
Rules
- Distillation is asynchronous maintenance. It must never block Stop hook completion.
- Failed sessions are valid sources when
[wisdom].distill_on_failure = true. - Store evidence pointers, not transcript dumps.
- Preserve reviewability: every accepted or queued lesson needs source id, timestamp, category, and rationale.
- Prefer explicit curation for permanent memory. Automatic distillation may queue candidates, but durable project constraints, rejected approaches, and branch-scoped decisions need evidence pointers and reviewable rationale.
Success Criteria
- Schema exists or is created.
- Accepted lessons are category-routed.
- Contradictions are queued or handled according to config.
- A distillation report records counts for accepted, queued, skipped, and errored candidates.
Anti-Rationalization
| Shortcut / Temptation | Why It Fails |
|---|---|
| Treat the skill as complete because the file exists | Skill contracts must describe observable behavior and verification, not just command names. |
| Skip artifact and safety checks for a small command | Small commands still mutate state or guide execution; preserve the same gates. |
Exit Criteria
- Command behavior matches the owning feature contract.
- Required reads, writes, and user-visible outputs are described.
- Safety, governance, and artifact constraints are preserved.
- Missing state produces a clear, non-destructive result.