retro

Retro — LLM-driven Session Retrospection

One efficient LLM pass over a session (or the stored memory backlog) detects friction, classifies it into one of six destinations, and materializes approved learnings.

Core principle: No silent writes — every materialization needs explicit per-proposal approval.

Modes

Detail per mode in references/workflow.md; full pipeline + commands in commands/retro.md.

• /retro — Sweep: the whole current session.
• /retro "<problem>" — Spotlight: one described issue.
• /retro outcome [session-id|--since N] — replay a past session by what happened to its output (reverts, rejected PRs, follow-up fixes).
• /retro audit [--scope project|repo|skill] — cross-session architectural drift, not per-session friction.
• /retro promote — inventory already-written local memory (all slugs) and re-home each note upward (skill-update › project-rule › user-memory; never project-local memory), draining the source only after the upward write is verified. See references/promote-mode.md.
• Auto — optional SessionEnd hook (hooks/session-end.json), off by default.

Pipeline (all modes)

1. Mechanical pre-pass — scripts/detect-mechanical.py (Promote substitutes scripts/scan-memory-inventory.py).
2. LLM enrichment — add inferential signals; filter false positives.
3. Cross-session enrichment (optional) — Coach events.sqlite or JSONL scan.
4. Discover skills — scripts/find-org-skills.py (installed + org catalogue); find the owning skill first.
5. Classify (classification-heuristic.md) to the broadest useful scope; never project-local memory.
6. Eval consultation — read a matched skill's evals/; propose a TDD stub.
7. Proposal generation — prose Why + How-to-apply, grouped, ≤10.
8. Approval — approve / edit / reject per proposal.
9. Materialize per destination; for Promote, drain the source last (verified).
10. Report.

Boundaries

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 that makes a private 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).

References

File	Purpose
references/friction-catalog.md	All ~32 friction signals (Schichten A/B/C)
references/destination-taxonomy.md	The six destinations
references/classification-heuristic.md	Friction → destination mapping
references/skill-discovery.md	Finding skills at runtime
references/patch-workflow.md	Source-repo patching (never cache)
references/eval-integration.md	Evals for context and TDD stubs
references/promote-mode.md	Promote: scan, classify, materialize-then-drain
references/workflow.md	All modes + pipeline phase selection