Tamircohen28 /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.
| Pattern | What it looks like | Why it costs |
|---|---|---|
| Unnecessary PR fan-out | Several PRs opened for what was one deliverable; workers opening PRs instead of committing and handing off | A work unit is not a delivery unit. N PRs mean N review cycles, N CI runs, and merge conflicts between siblings that a single integration branch would never have had. |
| Missed parallelism | Independent tasks run one after another; a single agent doing a broad read that several bounded agents could have split; dispatches issued in separate messages instead of one | Wall-clock time spent for nothing. Look for tasks with no dependency edge between them that still ran in sequence. |
| Repeated full validation | The whole test/lint/build suite run after every small edit, or by every worker on overlapping scopes | Tier 3 work done at tier 0 cost. Note which tier each run actually needed (spec §9) and how many runs were redundant. |
| Provider-specific failures | A step that worked on one platform and failed on another; a skill assuming subagents, hooks, a statusline or an artifact runtime that the running harness lacks; a capability claimed without a fallback | These are portability bugs, not bad luck. Name the capability and the platform; the fix is usually a capability gate, not a retry. |
| Orchestration deadlocks | Two agents waiting on each other; a worker blocked on a file another agent owns; an agent waiting on CI that its own harness may kill; a handoff that never arrived; a request written to a requests file that nobody read | Deadlocks are silent — the session just gets slower. Check every wait for who was supposed to end it. |
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.mdindex) 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.
| Finding points at | retro may | retro may NOT |
|---|---|---|
| Project memory, a project rule file, a repo hook | propose, then write on approval | write before approval |
core/**, rules/**, the capability registry, validation tiers, delivery policy |
propose only, as a written recommendation with its evidence | edit, even with approval — that is a deliberate change with its own review, not a retro side effect |
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.