Retrospective

Run a structured retrospective on a chunk of agent work and capture it as a GitHub issue, so the lessons outlive the chat. A retro that lives only in the conversation dies when the conversation does — filing it is the point of this skill, not an afterthought.

The goal is not a tidy write-up — it's changing what the agent does next time. Judge every retro by one test: would an agent that loads the routed fixes avoid the same correction? If a finding doesn't translate into a concrete behavior change at a durable home, it isn't done. Lean toward enforced homes (hooks, explicit gates) for anything the human had to insist on twice — compliance you can't rely on the model to remember belongs somewhere it can't be skipped.

Bias hard toward process, prompting, and input-document fixes over one-off coding errors. Coding mistakes are caught by verification and fade as models improve; process and input gaps recur on every task and every repo, and are what actually cost the human repeated course-corrections.

When to use

Use when the user asks for a retro, post-mortem, "what can we learn," or "how do we prevent this from happening again" — or after a multi-step task that had notable friction, mistakes, or course-corrections.

Not for a plain progress summary (use the recap skill) or a single one-off fix (use the prevent-mistake skill). This skill is for extracting systemic, reusable lessons and parking them somewhere durable.

Procedure

1. Scope it. Confirm what the retro covers — this session, a PR, a feature, a sprint.
2. Gather evidence — don't reconstruct from memory. Skim the real record: the conversation, the PRs/commits, review comments, CI runs. The highest-signal findings are the moments the agent had to be corrected or the human had to repeat themselves — mine those first.
3. Draft the retro using the template below.
4. Root-cause and classify every finding. Name one root cause, then tag it process / prompt / input-doc / code. Then route the fix to its durable home (see Routing), and state the behavior change it should produce ("next time the agent will…"). A finding with no routed fix and no behavior change is just a complaint.
5. File it as a GitHub issue (see Filing) — this is the deliverable.
6. Offer the follow-ups. Propose the routed changes (e.g. a global-config edit, a new hook, an ADR) as separate PRs. Never merge or apply them without explicit approval.

Retro template (the issue body)

# Retrospective: <topic> (<YYYY-MM-DD>)

**Scope:** <what work this covers — link the issue/PRs>

## What went well (keep doing)
- <thing> — why it worked, so it's repeatable

## What went wrong / friction (with root cause)
| # | What happened | Root cause | Class | Fix → home → next-time behavior |
|---|---|---|---|---|
| 1 | <observed> | <one root cause> | process/prompt/input-doc/code | <fix> → <durable home> → <what the agent does differently> |

## Highest-leverage changes (prioritized)
1. <change> — prevents <which findings>, lives in <home>

## Action items
- [ ] <change> — owner, destination (PR/file)

Routing fixes to durable homes

Match each fix to the layer with the right blast radius. Cross-cutting agent rules never go in per-repo files — that doesn't scale to many repos.

Fix type	Durable home	Scope
Identity / operating contract (gates, comms style, definition-of-done required)	~/.claude/CLAUDE.md (user-global)	every repo
Non-negotiables that must not be forgotten (e.g. never merge without approval)	~/.claude/settings.json hooks	every repo, enforced
Repeatable procedure	a skill in the synced skills library	every repo + machine
Per-repo design decision	that repo's ADR / AGENTS.md	one repo
Per-task expectations (done-definition, approvals, how to verify)	prompt / issue template	one task

Distinguish guidance from guarantees: a passive skill is guidance the model might load; a safety-critical step (the kind the human had to enforce) belongs in a hook or an explicit command, not a "remember to."

Filing the issue

Round-trip the body through a temp file (see the GitHub skill's issue-editing topic — never pass multiline content via inline --body):

# write the drafted retro to .tmp/retro.md, then:
gh issue create --title "Retrospective: <topic> (<date>)" \
  --body-file .tmp/retro.md

Title the issue Retrospective: <topic> so retros are easy to find later — no label needed, and the skill never mutates a repo's existing label taxonomy.

Print the issue URL. If the repo has no GitHub remote, save the draft to a file in the repo and tell the user where it is.

Notes

Keep the issue self-contained — a reader who wasn't in the session should understand each finding and its fix. Relates to the dev-methods skill (route content to the right medium) and the GitHub skill (issue + PR workflow).