agentleFS
ralfyishereralfyishere/rules-with-receipts/.claude/skills/self-improvement-loop/SKILL.md

Self-Improvement Loop

Skill2 starsChanged 4 months agoMITView on GitHub

Learn from prior mistakes and repeated patterns - review what failed, extract a reusable lesson, apply it to the next attempt. Activate when the user corrects your output, when an approach fails and needs a retry, when you notice the same friction recurring across tasks, and at the end of significant multi-step work. Trigger signals: "no, I meant...", "that's wrong", "try again", a fix that didn't fix, a second attempt at anything, or completing a task that took notably more iterations than it should have.

The file

We split this skill into the rules it gives an agent

3 rules. About 0 are common, 2 are distinctive, and 1 is very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈2

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    When the "failure" was actually a requirements change — that's memory-hygiene's superseded-context handling, not a lesson about your …

    line 23
  2. Distinctive:

    Step 6 — For repeated patterns, look for the upstream fix: If the same lesson keeps being learned ("verify before claiming" for the fourth …

    line 49
  3. Distinctive:

    No identical second failure: whatever the user corrected does not recur in the same session.

    line 63

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.