| name | improvement-loop |
| description | Diagnose and fix agent failures using the systematic improvement loop. Use when an agent makes a mistake, misses a requirement, or after any significant task. |
Improvement Loop
Every agent miss is a learning opportunity. The goal is to design an environment where the easiest path is the correct one.
The loop
- Capture the miss: what did the agent do, what should it have done, and what did reality say?
- Diagnose what it could not see: missing observability, instructions, tooling, guardrails, or verification.
- Choose the smallest useful primitive.
- Encode it as a version-controlled artifact.
- Promote repeated or high-risk misses into gates.
Primitive map
| Diagnosis | Artifact |
|---|
| Missing line knowledge | Update AGENTS.md, README.md, or docs/ |
| Missing queue knowledge | Update AGENTS.md or relevant product docs |
| Missing verification | Add or improve a test, script, checklist, or CI gate |
| Too much freedom | Add a guardrail or require human approval |
| Missing runtime visibility | Add logging, diagnostics, screenshots, or debug commands |
Promotion rule
If the same class of miss happens twice, consider promoting the fix from guidance to a gate. Good gates are cheap, deterministic, and tied to real risk.
