retro

Retro — LLM-driven Session Retrospection

On Codex, resolve script paths from this loaded skill directory and use the native discovery reader (find-org-skills.py --host codex), not Claude cache paths. Host selection and coverage limits: references/skill-discovery.md.

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 auto-trigger").

Pipeline (all modes)

1. Mechanical pre-pass — uv run ${CLAUDE_SKILL_DIR}/scripts/detect-mechanical.py (Promote: uv run ${CLAUDE_SKILL_DIR}/scripts/scan-memory-inventory.py). Every Python script runs through uv run: its header declares Python 3.11 or later, and python3 can be an older interpreter (macOS ships 3.9). 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. Codex rollout JSONL must first be converted with scripts/codex-transcript.py; on Windows set PYTHONUTF8=1 before uv run. Invocation and adapter limits are in references/workflow.md. Then uv run ${CLAUDE_SKILL_DIR}/scripts/collect-review-findings.py on the same transcript (its header also declares the tree-sitter parser; plain python3 stops with a message): review threads, bot reviews, and comments on the session's PRs/MRs, their linked issues, plus normalized tracker feedback supplied via --feedback-file (input for B18–B20, D4, D6). The subagents' transcripts (<session id>/subagents/agent-*.jsonl) are read with it; transcripts in the output lists every file read. PRs a script opened (a fleet driver's opened.jsonl) are not in the transcript: pass that file with --pr-list. Resolve relevant opaque hints through the owning integration, never by key shape. See references/feedback-contract.md; incomplete coverage is not silence.
2. LLM enrichment — inferential signals, both classes (friction + learnings B16–B20); filter false positives.
3. Cross-session enrichment (optional) — JSONL scan via ${CLAUDE_SKILL_DIR}/scripts/scan-cross-session.py.
4. Discover skills — ${CLAUDE_SKILL_DIR}/scripts/find-org-skills.py — and the repo's harness (project-harness-inspection.md).
5. Classify (classification-heuristic.md) — authority first, then broadest scope; never project-local memory.
6. Evals — read a matched skill's evals/; propose a TDD stub.
7. Proposals — prose Why + How-to-apply, grouped, ≤10; learnings survive the trim.
8. Approval — approve / edit / reject per proposal.
9. Materialize per destination; for Promote, drain the source last (verified).
10. Report.

Boundaries

Scope: session-end/cross-session analysis, skill-PR routing, done gate. Tracker identity and access belong to the owning integration; QA and time policy belong to project/organization rules. No implicit tracker, CLI discovery or organization-specific billing defaults in the core.

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, harness-invented attribution (a disclosure the user's rules prescribe is required), 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

File	Purpose
references/feedback-contract.md	Tracker-neutral evidence and reference resolution
references/friction-catalog.md	All signals: friction + learnings (A/B/C, B16–B20)
references/destination-taxonomy.md	The seven 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 + TDD stubs
references/promote-mode.md	Promote: materialize-then-drain
references/done-mode.md	Done: seven-gate finish check
references/workflow.md	All modes + phase selection