# Self Improvement Loop

> Repair a measured failure in agent routing, instructions, tool contracts, context, memory, or evaluation, then verify the repair and resume the original task. Use after a reproducible failed check, route mismatch, tool misuse, regression, or specific user correction. Do not activate from vague dissatisfaction or use it to increase permissions or autonomy silently.

- Skill: `ashermahonin/self-improvement-loop` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add ashermahonin/self-improvement-loop`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ashermahonin/self-improvement-loop/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: ashermahonin (https://skillmd.com/u/ashermahonin)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/ashermahonin/self-improvement-loop

---


# Self-improvement loop

## Purpose

Correct a specific weakness in the system around the model. This event loop changes prompts, skills, routing, tools, memory, or evaluations; it does not train model weights.

## Failure evidence

1. Read `references/improvement-loop.md`.
2. Save the resume point in the original task.
3. Record the triggering event, expected behavior, available logs or checks, and smallest reproduction.
4. Classify the failure: route, context, documentation, tool contract, prompt, memory, evaluation, permission, handoff, or implementation.
5. Decide whether the fault belongs to the product or the agent system. Route ordinary code defects to implementation.
6. Define one measurable improvement target and a stop condition.

## Repair cycle

1. Reproduce the failure and identify the first wrong decision supported by evidence.
2. Compare the smallest plausible repairs when the cause is uncertain. Verify current external behavior before changing a technical contract.
3. Change the narrowest durable surface: trigger description, route, procedure, reference, tool schema, context policy, memory rule, or evaluator.
4. Re-run the reproduction and one nearby non-regression case.
5. Add a behavioral regression check when it can catch the same failure class without matching preferred wording.
6. Write a short project-memory note only when the lesson is likely to help a future task. Use the active equivalent of `53-agent-learning-log.md`.
7. Resume the original task from the saved point.

## Event loop rules

- Run one observe, analyze, repair, validate, remember, resume cycle for a failure class.
- A new cycle needs new evidence, not a feeling that the previous repair was incomplete.
- Keep the user's task moving; process improvement is not the primary deliverable.
- Stop after two ineffective repairs for the same class and report the unresolved cause.
- Never increase autonomy, permissions, retention, external access, or unattended execution as an implicit repair.

## Permission boundary

- Preserve the original scope and permission boundary.
- Use current documentation when the repair depends on an external framework, SDK, MCP server, benchmark, or tool.
- Treat evaluator output as evidence to inspect.
- Keep the loop bounded by a measurable target, time or attempt budget, and stop condition.

## Improvement record

- Failure class and first wrong decision
- Baseline reproduction
- Narrow repair and changed artifact
- Before/after result and non-regression check
- Project-memory note when useful
- Resume point and remaining risk

## Resume criteria

- The reproduction fails before the repair and improves afterward.
- The patch targets a specific failure class and adds no generic prompt weight.
- Route changes are checked against neighboring entrypoints.
- Memory stores a reusable lesson, not a transcript.
- Acceptance includes project or task evidence, not evaluator opinion alone.
- Two ineffective attempts trigger a stop.

## Handoff

Report the failure class, changed artifact, before/after evidence, regression protection, remaining risk, and exact point where the original task resumes.

## References

- `references/improvement-loop.md`: failure taxonomy, repair order, memory rules, and regression design.