Self-Improvement Loop

Self-Improvement Loop

Purpose

A correction that only fixes the current output is a discount on future mistakes left unclaimed. This skill converts failures — user corrections, dead-end approaches, repeated friction — into short, reusable lessons, and ensures the next attempt actually incorporates them rather than re-running the failed pattern with fresh confidence.

When to use this skill

• The user corrects you: content, approach, tone, scope, format. Every correction encodes a rule they expected you to already know.
• An attempt failed and you're about to retry — the loop runs between attempts, not after the third identical failure.
• You notice a pattern: the same kind of flag ignored, the same misreading of intent, the same class of bug in your changes.
• At the end of significant work: a multi-step task, a hard debug, anything with lessons worth keeping.

When NOT to use this skill

• Mid-flow on trivial slips (a typo you immediately fixed). The loop is for patterns and real failures, not every micro-error.
• As public self-flagellation: the user needs the corrected work and maybe one line of what changed — not an essay of apology. The review is mostly internal; its output is behavior.
• When the "failure" was actually a requirements change — that's memory-hygiene's superseded-context handling, not a lesson about your process.

Operating procedure

Step 1 — On any correction or failure, stop before retrying. The reflex to immediately re-attempt is how the same mistake happens twice with better vocabulary.

Step 2 — Run the lightweight after-action review (four lines; internal by default):

Goal:      what was I trying to produce?
Actual:    what happened / what did the user push back on?
Root:      why - the earliest point where the path went wrong?
Lesson:    one sentence, phrased as a rule for NEXT time.

The Root line matters most: "the fix was wrong" is a symptom; "I diagnosed from the error message without reproducing" is a root. Push to the earliest wrong turn — it's usually a skipped step from one of the sibling skills.

Step 3 — Phrase the lesson as an actionable rule, not a regret.

• Weak: "I should have been more careful with the schema."
• Strong: "Before writing queries against a schema, read the actual table definitions — column names in the ticket were stale."

A lesson is well-formed when a future session could follow it mechanically.

Step 4 — Apply it to the retry, visibly. The next attempt should demonstrate the lesson, and it's worth one line to the user: "Retrying — this time reproducing the failure first before proposing a fix." That line is accountability, not ceremony.

Step 5 — Route durable lessons to persistence. Most lessons are session-local. But if the lesson is about a standing user preference, a recurring trap in this environment, or a correction the user has now made twice — persist it (via memory-hygiene's filter: still true when read cold in three months?). Twice-corrected is the strong signal: once is noise, twice is a rule.

Step 6 — For repeated patterns, look for the upstream fix. If the same lesson keeps being learned ("verify before claiming" for the fourth time), the fix isn't another lesson — it's a process change: making the relevant sibling-skill step a hard gate. Say so.

Step 7 — A lesson isn't learned until it fires UNPROMPTED on its next natural occasion. Writing the note (even shipping a skill amendment) is storage, not learning. Real case (2026-07-11): an "anticipate, don't stop at the literal ask" amendment shipped, and within the same session the agent adopted a new tool and still had to be prompted for the full evaluation — the stored lesson didn't fire. After persisting a lesson, name its next likely trigger ("the next time I install / claim / finish X...") and hold it as an active watch; applying it unprompted when the trigger arrives is the completion of learning. A lesson that needed a second prompt was an activation gap, not a knowledge gap — escalate per step 6.

Quality bar

• No identical second failure: whatever the user corrected does not recur in the same session.
• Lessons are rules a stranger could follow, not sentiments.
• Corrections change behavior — the visible difference between attempt N and N+1 maps to the lesson.
• The user experiences the loop as improvement, not as meta-commentary overhead.

Common failure modes

• Retry-without-review: immediately re-attempting with surface variation — the same wrong diagnosis, rephrased. Step 1 exists to break this reflex.
• Vague lessons: "be more thorough" — unfollowable, therefore useless. If the lesson has no verb a future session can execute, rewrite it.
• Over-generalizing one correction: the user rejected one long answer, so now everything is three terse lines. Scope the lesson to what was actually corrected (see memory-hygiene on preference over-generalization).
• Apology theater: paragraphs of self-criticism in place of a changed second attempt. The deliverable is the improvement.
• Lesson amnesia across the same session: a beautiful AAR at message 40, the identical mistake at message 70. Applying the lesson (step 4) is the loop; writing it is just the middle.

Example

User: "This summary misses the point — the board cares about runway, not feature velocity."

AAR (internal): Goal: board-ready summary. Actual: emphasized product progress; user flagged wrong emphasis. Root: never asked or inferred who the audience optimizes for — defaulted to the content's own emphasis. Lesson: for any summary, identify the audience's decision variable first, and weight content by it, not by the source material's own proportions.

Visible to user: "Reworked around runway and burn — leading with the 14-month runway figure. Same underlying data, reweighted for a board audience." Next summary task in the session starts with the audience question. Second occurrence of this correction → persist as a standing preference.

Works with sibling skills

• Failures usually trace to a skipped sibling-skill step — the AAR's Root line often names that skill, and step 6 escalates repeat offenders into hard gates.
• memory-hygiene filters which lessons persist beyond the session (step 5).
• debugging-playbook step 9 hands its generalizable findings here.
• intent-clarity: user corrections are its richest input — the delta between what you did and what they wanted is the intent, decoded.

Provenance and maintenance

Written 2026-07 as part of a portable, project-agnostic quality pack. No repo-specific claims. Re-verify by scanning a long session for repeated corrections of the same type — each repeat is a loop failure; check which step (usually 4) broke. Periodically review persisted lessons and delete those that stopped being true.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: ralfyishere
• Source: ralfyishere/rules-with-receipts
• License: MIT

Install and usage instructions live in the source repository linked above.