/retro — session postmortem & self-improvement

Analyze this session's transcript and turn its friction into durable improvements. Do NOT write any files until the user approves the proposal.

Timing — when to self-trigger

A retro belongs at the end of a session. This skill is model-invocable so it can catch rough sessions the user forgot to review — but do not let it derail active work:

• Mid-task: if you notice a rough stretch while work is still in progress, do not launch a full retro. Finish the task first, then briefly offer one: "This was a bumpy stretch — want a quick retro to capture the lessons?"
• Session wrap-up / user signals done: proactively offer the retro when there was real friction (repeated failures, rework, multiple corrections) and none has run yet.
• User asks explicitly: run it now.

Because retro only proposes changes and never writes without approval, offering is always safe — the cost of a mistimed offer is one declined suggestion.

1. Friction report

Scan the session and bucket what went wrong.

Execution friction

• Low-quality output — wrong/incomplete results, rework, claims made without verification.
• Slowness / looping — wasted time, redone work, the same approach retried without a success criterion.
• Repeated mistakes — anything that went wrong more than once.

Orchestration friction

These are the failures that only show up in multi-agent work, and they are invisible unless you look for them by name. Check each one explicitly — "no instances" is a valid, useful answer, and a far better one than not having checked.

For each item give: what happened (1 line) · root cause (1 line) · fix layer (hook / rule / memory / skill / command / policy).

Distinguish an incident from a pattern. One occurrence is an incident; propose a fix only if the cost was real. Two or more is a pattern and deserves a durable change. Say which you are looking at — inflating a single mishap into a permanent rule is how rule files rot.

2. Proposed changes table

Present a table: Problem → Root cause → Fix layer → Exact change. Route to the right layer:

• Hooks for absolutes that must happen every time (lint/format/verify gates, sensitive-file guards).
• CLAUDE.md rules for guidance/conventions/definition-of-done.
• Memory (…/projects/<project>/memory/*.md + MEMORY.md index) for distilled lessons — the SIGNAL, not a transcript replay.
• Skills / slash commands for repeatable multi-step workflows.

Keep it lean — propose the smallest change that fixes a problem that actually occurred. Don't invent rules for problems that didn't happen. Prefer hooks over advisory text when something must be enforced.

Framework policy is proposed, never edited

Orchestration findings often point at framework policy — the role definitions in core/, the capability registry, the rules under rules/, the validation tiers, the PR/delivery policy. This skill never modifies any of them. It writes a proposal and stops.

A retro that silently rewrites framework policy makes the framework unauditable: the next session inherits a rule nobody decided on. State the recommendation, cite the sessions that motivate it, and let a human open that change explicitly.

3. Stop and wait

Ask the user to approve, edit, or cut items. Do not create or edit any files (especially hooks / settings.json) until they say yes. Framework-policy items stay proposals regardless of the answer — approval routes them to a separate change, it does not authorise an edit here.

4. On approval

Make only the approved changes, and only in the layers this skill is allowed to write. Then list every file created/changed, what each does, and how to undo it. Remind the user to commit .claude/ config + the memory dir so it's reviewable and survives machine changes.