When an agent does something wrong, you fix it in the chat, and it works. The code is right, the tests are green, and you move on. Do that for a few months and you find out that:
- every session starts from nothing. The agent has never seen your last conversation and knows only the code and the files it reads. The agent that starts tomorrow is the same agent you corrected today;
- a correction in the chat fixes today's code, not tomorrow's agent. Tomorrow's session reads neither your prompt nor the line it fixed, so it makes the same mistake in the next place and you type the same correction again;
- the same mistake keeps coming back, and no single session can see it. On its own each one is nothing. When I read a batch of Cockpit's pull requests together, a large share of the review comments turned out to be about how the text was written, not about the code.
So the agent learns nothing on its own. Learning only happens if you build the loop that makes it, and I do that at two levels, each with its own skill: /session-review after every session, and /periodic-review every few weeks, across many.
After every session: /session-review
By the time you could write down what you corrected, the work is finished and the next thing is already waiting, so almost nobody does it. A skill has to do it for you, at the moment the session ends, and it has to keep the guidance short, or nobody reads it.
- Run
/session-review at the end of every build, and turn your corrections into rules. The skill reads the whole conversation back, finds every correction you made, and proposes the rule that would have prevented it. You pick which ones to write, and it puts each one in the file the next agent reads at the moment it matters. It opens a pull request with no product code in it, only rules. In Cockpit it runs by itself as the last step of /build, so it never depends on someone remembering.
- Only write a rule that could matter on different work. Most of what a session throws up is true of that one piece of work, or of how you personally like to work, and never again. A rule earns a place only if the same mistake could come back on a different task. Cockpit's skill keeps at most three, and finding none is the normal outcome.
- Make every running session pick up a rule that was merged while it worked. A session reads its guidance once, when it starts. A rule you merged an hour ago changes nothing about what a running session believes, and with ten sessions going, each can spend hours working against a rule that changed underneath it. Mine did. So every session checks what the guidance gained since it started, before it finishes. The rule is in Cockpit's CLAUDE.md.
Across many sessions: /periodic-review
Nothing in a normal week asks you to look at more than one ticket at a time, so a mistake spread across twenty of them never gets looked at. Every few weeks, one session gets the job of reading everything that had to be corrected since the last look, and proposing a fix for each mistake that repeats. It writes no code.
- Run
/periodic-review every few weeks over everything that had to be corrected. It reads the pull requests merged and the tickets closed in the last four weeks, and collects every correction, every review comment and every review finding that was declined. Then it opens the original ticket and pull request of each one and decides where the mistake got through: a test that was never listed, a rule that existed and was skipped anyway, no rule at all, or a scope that was reversed once someone saw it. That decides the fix: a skipped rule gets a check, never another rule.
- Count a mistake only when it repeats, and fix a whole class with one test. One review comment is noise; two of the same kind are a pattern. Cockpit's skill groups instances by the mistake, not the wording, and where a class of mistakes shows up twice or more, the fix is one test that rules out the class, not a patch per instance.
- Ask for tickets, not a report. A report gets read once; a ticket gets built. Cockpit's skill shows at most seven proposals, ranked by how often the mistake happened times what it cost, and files only the ones you pick, each through
/scoping like any other change. One run came back with thirteen tickets, and not one of them was a feature.
- Keep the guidance lean. Every rule you add is one more thing every agent reads on every task. So prefer a test or a check over prose wherever one can decide the case, edit an existing rule in place rather than adding a new one, and remove a rule once a check makes it redundant.