retro

Retro

Find the moments where a session struggled, and propose changes to the environment of the agent that prevent them next time. The environment is everything that the agent reads or runs: checks, pointers to files, review rules, steering files, tools, and access to information. Retro does not fix the code of the task, and it does not change anything that the user did not choose.

Evidence

Each candidate must point to one moment of this session or of a past run: a friction entry, a failed command, a finding, or a correction from the user. Drop a candidate that you cannot trace to such a moment, even when it is good general advice. Two candidates are exceptions: a repository with no guardrail, and a check to remove. The sections below describe them.

If no moment is left to learn from, say so and give no candidates. Do not invent candidates to fill the categories.

Read these sources:

• the current session;
• the progress file of the ship run, if there is one. Its Friction section has one friction entry for each moment where the run struggled. The ship skill describes the format of the entries;
• the last 10 progress files that have status: finished and a Friction section, sorted by started, from all branches and worktrees. They are in the ship directory inside the directory that git rev-parse --path-format=absolute --git-common-dir prints. If the directory does not exist or this is not a git repository, skip this source. Use these files to find friction that repeats across runs.
• the skill feedback file, when the current repository is the source of a skill. The section "Candidates about skills" describes it.

Categories

Sort each candidate into one category. The category tells where the fix goes.

• Navigation. The agent searched long for a file or a fact. Add a pointer to it from a file that the agent already reads.
• Automated checks. The agent made a mistake that a tool could catch. Add a lint rule, a type, a test, a pre-commit hook, or a CI job. First read the check commands and the CI workflows of the repository. If a check exists but does not run, the fix is to connect it. If the repository has no guardrail, that is no pre-commit hook and no CI job that runs its checks, report this as a candidate.
• Review rules. The diff review missed a mistake, or found the same kind of mistake again. A confirmed final-check finding means that the diff review missed it. A failed check that caught a mistake needs no candidate, unless the failure repeats or cost much time. Classify the mistake first:
  • A mechanical mistake, such as a banned API, an import shape, or a file in the wrong place, gets an automated check, not a rule in text.
  • A judgement call, such as consistency across files or the style of the surrounding code, gets a rule in the standards document of the repository, such as CONTRIBUTING.md. If the repository has no such document, propose to create CODING_STANDARDS.md. The reviewer reads this document. Do not put the rule in AGENTS.md or CLAUDE.md.
• Steering files. AGENTS.md, CLAUDE.md, or a similar file is large. Move its rules to the standards document or to a check, and keep pointers.
• Tool economy. A tool call cost much for what it returned. Make the call narrower, or replace the tool.
• No-ops. A line in a steering file does not change what the agent does. Delete it.
• Information access. The agent needed information that it could not get. Give it access, such as a log file of the dev server or read-only access to a service.