retro looks back over a coding session and suggests changes to the agent's environment, not the code. The environment is everything around the code that shapes how the next agent works: instruction files like CLAUDE.md, navigation pointers to the right files, automated checks such as lint, typecheck and tests, coding standards, and tooling.
Its rule of thumb: a mechanical mistake (a fixed pattern a program could spot) becomes a deterministic check, meaning an automated check that gives the same answer every time, such as a lint rule or a CI job. A judgement call becomes a coding standard for the reviewer. The next build then starts from a better environment.
When to use it
After a build, and especially one that went sideways: the agent hunted for files, repeated a mistake, or a check you expected never ran.
After a hard bug is fixed, to ask what would have prevented it.
In the session it's looking back on, before you clear it. After clearing, point it at that session's log instead.
retro has model invocation turned off, so the agent never reaches for it by itself. You call it.
When not to use it
To check whether the code itself is right, use code-review. It reviews the diff against the standards and the Spec. retro looks at how the work went, not at the diff.
To carry unfinished work into a fresh session, use handoff.
To fix the bug you just hit, fix the code first. retro comes after the fix.
What it needs to start
A session to look back on: the current one by default, or a session log you point it at.
The repo's own check commands and CI workflow, so it can spot a check that exists but isn't wired up. A repo with no guardrail (no pre-commit hook and no CI job running lint, typecheck and tests) is itself a finding.
It calls the writing-for-agents Skill first, for the style of anything it suggests writing.
What it creates
A list of candidate improvements, presented to you in order of severity. Each sits in a category such as navigation, automated checks, coding standards or tool economy. retro suggests; it doesn't change files, open Issues or open pull requests on its own. You choose which suggestions to act on.
Going deeper
6 min read · Going deeper not read
Why it exists
retro graduated out of in-progress/ into the Engineering bucket in version 1.3, in Matt's changelog updated 5 October 2026. The changelog lists it under "New: /retro", one of the three skills that "graduate out of in-progress/ into the Engineering bucket". His reason was that keeping a repo in good shape had fallen to you: "My skills ask a lot of you." "I was doing this by hand on my own repos, so I bundled it into a skill."
He also says why it reads the session rather than the result: "It reads the real session, so it sees the problems the agent hides from you. The agent does not complain as much as it should. It pushes on, and the feature gets built anyway."
In his AI Engineer Paris talk (published 25 September 2026), he said "I'm gonna be shipping version one point three this week" and put the aim in one line. When you review, "you're not just reviewing the code, you're reviewing the system that creates it." And "you never want to write the same comment twice".
His changelog sums it up:
So the loop is: find a mistake, run /retro, and make the mistake impossible next time.
From snapshot/skills/ask-matt/SKILL.md, line 34: “/retro closes the loop. After a build, and especially one that went sideways, it looks back over the session and suggests changes to the agent's environment, not the code: navigation pointers, automated checks, the coding standards /code-review enforces, steering files, tooling. Mechanical mistakes become deterministic checks; judgement calls become coding standards. The next build then starts from a better environment.”
The name comes from team practice. Matt's changelog says "/retro (user-invoked) is short for retrospective." Martin Fowler wrote in 2012 that the Retrospective Prime Directive "has been in integral part of retrospective thinking since Norm Kerth first launched the practice." Kerth's directive asks a team to believe "that everyone did the best job they could, given what they knew at the time, their skills and abilities, the resources available, and the situation at hand." Matt's page says retro "asks what in the repo let them happen".
Rules go where there is room for them. The Skill file explains why a judgement call goes to the reviewer. "The implementation agent has the most context pressure." It explores, writes code and debugs. "The review agent has the least context pressure - it receives a diff, so no exploration needed." A line in CLAUDE.md costs more than it looks. Matt's page says it "loads into every session, gives less weight to everything else in the file, and goes out of date as the code changes." That is also why retro "is not a memory system. It does not store what happened."
The check-first rule is newer than the Skill. On 15 September 2026, Matt wrote that "retro currently funnels every reviewer-agent gap into the same fix: add a line to CODING_STANDARDS.md." For a fixed pattern, that "just asks the reviewer agent to re-derive the same call on every future diff, forever, instead of paying for a check once." His pull request #1083 added the mechanical-or-judgement split and the "no guardrail" finding that today's Skill file has.
A real example
On 2 September 2026, a user filed issue #1010 in Matt's repo, an AI-drafted report on a full run of implement-spec. "Afterwards, the same session ran a /retro skill over its own transcript." A subagent pulled "every orchestrator turn and tool call from the session JSONL". The report goes on: "Two further review subagents then worked the draft over without session context", and one of them attached a proposed sentence to each item. The fixes were sentences for the implement-spec Skill, not code.
One finding shows retro's purpose. When a merged Ticket's check failed for a cause outside that Ticket, the orchestrator "diagnosed inline: 60 tool calls, and most of the run's peak context." That count came from the retro's transcript extract. The later review pass proposed the fix, a sentence in the Skill that sends such a failure to "a diagnosing subagent". A sharper Skill is the kind of environment fix retro looks for: "keep the skills sharp" is one of the jobs Matt says it took over.
Where it goes wrong
Generic advice. Matt calls this "the strongest criticism" of retro. One user found the AI "invents generic advice to satisfy the retro categories." His answer: "Discard any candidate you can't trace to a specific moment." Treat the severity order "as a first draft too, because a quiet, expensive mistake can rank below a loud, cheap one."
Noise on every run. Issue #1173 (5 October 2026) points out that each category's "Use when" is "ordinary friction that every real session has", so every run produces a list. The reporter's team saw "17 retro runs across 12 sessions", and 15 of 17 were followed by the user asking the agent to prove the candidates were needed. They suggest one check per candidate before showing it, and say "Zero survivors is a complete retro." Matt labelled the issue ready-for-human on 7 October. The Skill file at the 29 October pin still has, as its last step, "Present these candidates to the user, in order of severity."
Automating it. "Most people ask me how to automate it. Do not. An automated retro finds false positives, keeps fixing them, and takes your repo somewhere it should not go." Run it on a sample of sessions, or "on a session where the agent did something odd."
Checks pile up. Matt calls removal "its weakest spot". retro "does not audit the lint rules, hooks, or CI jobs it proposed last month." So "You must still prune checks yourself. A rule that fires constantly on good code is the sign to remove it."
Try it
In your practice project (set it up first with keeping-track's Try it step if you haven't), pick the session where an agent built or changed the booking endpoint in api/. If that session is still open, type /retro before you clear it; if not, point a fresh /retro at it in the session logs.
For each candidate, find the moment in the session it came from. Cross out any you can't trace.
Issue #1173 suggests one check per candidate; try that by hand. For each survivor, write down the narrowest check that could show it isn't needed: a git log, a count in the session, a docs read. Run it.
If a survivor is mechanical, accept it as a check, such as a lint rule run by .github/workflows/ci.yml. A proposed check "is code like any other, so try it against the repo before you let it block merges": open a pull request and watch CI run it on your existing code first.
If nothing survives, you're done. #1173's reporter counts that as a complete retro.
From snapshot/skills/retro/SKILL.md, line 18: “A repo with no guardrail (no pre-commit hook and no CI job running its lint/typecheck/test command) is itself a finding”
From snapshot/skills/retro/SKILL.md, lines 31–35: “The implementation agent has the most context pressure. They are responsible for exploration, writing code, and debugging failures. The review agent has the least context pressure - it receives a diff, so no exploration needed.”
From snapshot/web/github.com/mattpocock-skills-pull-1083.md, line 31: “retro currently funnels every reviewer-agent gap into the same fix: add a line to CODING_STANDARDS.md. That's the right call for a judgement call, but for a fixed syntactic pattern it just asks the reviewer agent to re-derive the same call on every future diff, forever, instead of paying for a check once.”
From snapshot/skills/retro/SKILL.md, line 19: “Classify the violation first: a mechanical one (a fixed syntactic pattern, a banned API, an import shape, a file-location rule) gets a deterministic check, full stop”
From snapshot/web/github.com/mattpocock-skills-issues-1010.md, line 55: “Two further review subagents then worked the draft over without session context: one to cut anything a stranger to the repo could not digest and to attach a proposed sentence to each item”
From snapshot/web/aihero.dev/skills-retro.md, lines 129–131: “This is the strongest criticism of it. One user found that "once the job is finished, the AI tends to forget the struggles from the middle of the session and invents generic advice to satisfy the retro categories."”
From snapshot/web/aihero.dev/skills-retro.md, line 131: “Discard any candidate you can't trace to a specific moment. Treat the severity order as a first draft too, because a quiet, expensive mistake can rank below a loud, cheap one.”
From snapshot/web/github.com/mattpocock-skills-issues-1173.md, line 71: “Then run the narrowest check against the session logs, the repo or git history that could show it isn't, aimed at consequence (did it cost something, will it again) rather than occurrence. Present only survivors, each with its check and result. Zero survivors is a complete retro.”
From snapshot/web/aihero.dev/skills-retro.md, line 127: “It does not audit the lint rules, hooks, or CI jobs it proposed last month. It sees one session, so it cannot tell you that a rule now fires too often or that the bug behind it is gone. You must still prune checks yourself. A rule that fires constantly on good code is the sign to remove it.”