# Reflexion Loop — turning repeated corrections into permanent rules — a Claude Code skill *Part of the Wasser AI Academy skills library. Free to use.* **What it is:** the capture-and-graduate half of a self-improving setup. It records what went wrong in *how* a session ran, keeps those lessons short and deduplicated, surfaces the recent ones at the start of the next session, and promotes the ones that keep recurring into your permanent standing instructions. The point is simple: every repeated correction is a missing rule, and this is the routine that writes it. **Install:** save this file as `~/.claude/skills/reflexion-loop/SKILL.md` (create the folder). Claude Code picks it up automatically. Using Codex or another agent? Paste the content into your `AGENTS.md`. **Pairs with:** the `session-close` skill. Session close saves what happened; this saves what it taught. Run them together at the end of a session, or run this one on its own when the user asks you to scrape a session for lessons. --- Here is the problem this solves. The user corrects you on Monday. Chat sessions are stateless, so on Thursday you make the same mistake, and they correct you again. Nothing is broken, but the highest-signal information about how this person wants to work is evaporating every single day. This skill catches it. A note on paths. This assumes a lessons file and a standing-instructions file. `LESSONS.md` and `CLAUDE.md` (or `AGENTS.md`) are the conventional names. Point them at whatever the user actually has. The rules matter more than the filenames. --- ## 0 — When to run Run when the user asks for it: "scrape this session for lessons", "what did you learn", "/lessons", or as the last step of a full save. **Do not run this automatically at the end of every session.** That was the original design and it was wrong. A forced retrospective interrupts at the worst moment: the work has just clicked, the next thing is already in mind, and being stopped to reflect turns the habit into something to get past. Make it pull-based and it survives. Force it and it gets switched off. The routine save (daily note, project notes, task board) can and should be automatic. This step waits to be asked. --- ## 1 — Decide whether there is anything to capture Write a lesson only if one of these happened: - **The user corrected you, or repeated an instruction.** The strongest signal there is. - **You missed a chance to be proactive.** You had the information to surface something, check memory, catch a contradiction, or flag drift, and you didn't. - **A tool or approach had a gotcha** worth remembering: a flag that silently does nothing, a command that needs elevation, an API that rate-limits before it errors. - **You learned something durable about how this person works.** Preferences, tolerances, the order they like things in. Capture **how the work went, not what got built.** "Shipped the pricing page" is a project note; it will never change a future decision. "Ask which environment before deploying, the user runs two" will. **Zero lessons is a valid and common outcome.** If the session taught nothing about how to work, say "nothing worth capturing" and stop. A manufactured lesson is worse than none: it dilutes a file you are asking every future session to read. Cap it at three. If a session produced more than three, pick the three that would most change the next session. --- ## 2 — Check for a duplicate before writing Read the existing `## Recent` entries first. If one of them already says what you are about to write, **do not write a near-copy. Bump its `Recurrence:` count and update its date.** This is not tidiness, it is signal. Four differently-worded entries about the same friction read as clutter and get skimmed. One entry at recurrence four reads as a demand, and the count is what drives graduation in step 4. Match on the *rule*, not the wording. "Don't use em-dashes" and "stop putting dashes in the copy" are the same lesson. --- ## 3 — Write the entry Insert under the `## Recent` heading, newest first, in this shape: ``` ### YYYY-MM-DD · [agent] **What happened:** **Rule:** **Recurrence:** 1 ``` - The **title is the rule**, not the story. It is what gets scanned. - **What happened** stays concrete and short. Enough to recognize the situation, not a transcript. - **Rule** is written as a command. If it does not start with a verb, rewrite it. - Tag which agent or tool it applies to when you run more than one. **Placement is a real failure mode, not a style note.** If a session-start hook extracts everything below a specific heading, an entry written *above* that heading is invisible to every future session, forever. This has happened: the file looked healthy and nothing in it was ever read. Insert **under** the heading, never above it. If you are unsure what your hook reads, say so and ask the user to check. --- ## 4 — Graduate what has earned it A lesson graduates into the standing instructions when either is true: - **Recurrence has reached three.** It has proven it is not a one-off. - **A single instance cost real money or a real afternoon.** Some lessons do not need a second occurrence. To graduate one: 1. **Rewrite it as an imperative** in the standing instructions file. Commands, not anecdotes. "Never call a deploy done without loading the live URL" goes in. The story of the night it went wrong does not. 2. **Move the original entry** from `## Recent` to `## Graduated`, keeping its recurrence count as the record. 3. **Cut something.** Standing instructions load on every session and compete for attention with everything else in the file. Adding a rule without removing a stale one is how that file grows into something the model skims. Look for a line that is no longer true and remove it in the same edit. If nothing qualifies this pass, graduate nothing. This is a monthly-cadence move, not a per-session one. --- ## 5 — Prune `## Recent` holds about **ten** entries. When adding pushes it past that, the oldest entries either graduate (step 4) or move to `## Graduated` as closed. The cap is the feature: a file of fifty lessons is an archive, and archives do not get read at session start. Leave `## Graduated` uncapped. It is the audit trail of where your standing rules came from, and it is the thing to read when a rule stops making sense. --- ## 6 — Report Tell the user, briefly: - How many lessons were written, or that none were. - Which entries had their recurrence bumped instead. - Anything that hit the graduation threshold and now needs a decision. Three or four lines. If nothing was written, one line. --- ## The short version - **Pull, not push.** Run on request, never as a forced end-of-session interruption. - **How the work went, not what got built.** Project notes own the what. - **Zero is a valid outcome.** Do not manufacture entries. - **Bump recurrence, never write a duplicate.** The count is the signal. - **Insert under the heading the hook reads, never above it.** An unread lesson file is not a loop. - **Graduate on evidence** (recurrence three, or one expensive instance), rewrite as an imperative, and cut something in the same pass. - **Cap `## Recent` at ten.** Enforce it every time you add. Run 1 through 6 in order when asked. The payoff is not dramatic and it compounds: by month four the agent is annoying about different things than it used to be, which is what improvement looks like from the inside.