Retro — LLM-driven Session Retrospection

One LLM pass over a session or the memory backlog detects friction and reusable learnings, classifies each into one of seven destinations, and materializes approved ones.

Core principle: No silent writes — every materialization needs approval.

Modes

• /retro — Sweep: the whole current session.
• /retro "<problem>" — Spotlight: one described issue.
• /retro outcome [session-id|--since N] — replay a past session by its

outcomes.

• /retro audit [--scope project|repo|skill] — cross-session architectural

drift.

• /retro promote — re-home already-written local memory upward (never

project-local memory); drain the source only after the upward write is verified. See references/promote-mode.md.

• /retro done — definition-of-done gate: seven evidence-backed checks

(task, findings, retro, cleanup, questions, tickets, time), each ✅ / ❌ / ⏸ / N/A. ⏸ only when a named person can close it with a named action; what is structurally absent is N/A with its reason — a ⏸ nobody can close makes the whole table get skipped. Say done when every row is ✅ or N/A. See references/done-mode.md.

• Auto — optional SessionEnd hook, off by default. It is plugin-level, not

part of this skill directory: hooks/session-end.json at the repository root (see README, "Optional SessionEnd hook").

Pipeline (all modes)

1. Mechanical pre-pass — ${CLAUDESKILLDIR}/scripts/detect-mechanical.py (Promote:

${CLAUDESKILLDIR}/scripts/scan-memory-inventory.py). It requires --transcript-file, and the transcript is located by content — a token from this session — never by mtime: several sessions share one project slug, so the newest JSONL is regularly somebody else's. Invocation in references/workflow.md.

1. LLM enrichment — inferential signals, both classes (friction + learnings

B16–B18); filter false positives.

1. Cross-session enrichment (optional) — JSONL scan via ${CLAUDESKILLDIR}/scripts/scan-cross-session.py.
2. Discover skills — ${CLAUDESKILLDIR}/scripts/find-org-skills.py — and the repo's harness (project-harness-inspection.md).
3. Classify (classification-heuristic.md) — authority first, then broadest

scope; never project-local memory.

1. Evals — read a matched skill's evals/; propose a TDD stub.
2. Proposals — prose Why + How-to-apply, grouped, ≤10; learnings survive the

trim.

1. Approval — approve / edit / reject per proposal.
2. Materialize per destination; for Promote, drain the source last (verified).
3. Report.

Boundaries

Scope: session-end/cross-session analysis, skill-PR routing, done gate.

Always: LLM is primary classifier. Patches go to source repos, never the cache. Per-private-repo confirmation. Conventional Commits. DCO sign-off (git commit -s). Preserve commit signing.

Ask first: skill-match ambiguity, auto-mode activation, private-repo targets, dirty-worktree fallback, any promotion making a note team-visible.

Never: auto-merge, silent writes, bot attribution, skip hooks (--no-verify), patch the cache, hardcode a static skill list, rm a drained memory (tombstone); from Done mode: merge, tag or deploy, or touch another session's containers, processes or worktrees.

References