Guide · 2026-10-30
Make your agent write down what it got wrong
What you'll have: a small file of one-line lessons that every task reads at startup — plus the three questions that stop a "lesson" from being a restatement of the bug you just fixed.
What's real here: I run this as files, not as a feature. Every agent in my workspace keeps a
MEMORY.mdand a dated log beside it, and the project I'm writing this from keeps a 238-lineAGENTS.mdof rules that agent reads before it starts. Two of the lessons quoted below are from this week, in this project. What I haven't done is measure the effect — I can tell you the same correction stopped getting written twice, not that it made the agent faster. The 91% number further down is somebody else's result, on 2023 models.
The problem this fixes
Telling an agent "don't do that again" works for exactly one task. The next task starts from nothing, and you write the same correction again. A week later you're the memory.
That was me: the same three or four corrections, over and over, to different agents, because none of them could read what the last one had been told.
The file
One file per team, plain markdown, one line per lesson. Not a log, not a diary, not a summary of what happened — a rule that changes what the agent does next time.
# Lessons
- A fade from zero leaves ~0.2s of empty frame at every cut. Over 18 cuts it reads as flicker.
The line has to be readable the instant it arrives: hard cut, animate position only.
- Single-pass loudnorm at I=-14.5 overshoots true peak (+1.58 dBTP). The spike is at the
join, not in the speech, so gain doesn't fix it. Chain loudnorm with alimiter(-1.5 dBTP).
- A green build log proves compilation, not that the page renders. Check the typecheck line
and open the preview before saying done.
Both of the first two came from getting them wrong first. The third came from shipping a green build that 500'd.
The three questions
This is the part that makes the file worth having. A lesson that fails any of the three is a symptom wearing a lesson's clothes, and it will keep the next agent stuck on the wrong role.
- Does it name a cause, or a symptom? "The video had a black stretch" is a symptom. "Frames with no line on them are still frames" is a cause. One of those tells the next agent where to look.
- Where in the pipeline did it come from — the plan, the doc, the config, or the judgement? If the last three videos all opened on an empty screen, that's not an agent being careless, that's a missing rule in the format. So the lesson belongs in the format's docs, not in a reminder to be careful.
- Which step owns the fix? A lesson with no owner gets "noted" forever. If the cause is a plan that never said which folder, the planner owns it; if it's a check that never reproduced the problem, the checker does.
The size budget
Cap it. Ours is about 1,500 tokens — roughly 40 lines, or one screen. Two reasons:
- A file that grows without limit stops being read. The whole mechanism depends on the agent hitting it at the start of every task, and a 6,000-token file either gets skipped or gets you a worse answer.
- A full file is a signal. When you have to delete a line to add one, you find out which lessons actually keep paying. The ones that never came back are the ones to drop.
When the file is full, merge two lessons into one, or delete the one that hasn't applied in a month. Never raise the cap to fit new lines.
How it gets read
The file is only worth writing if it's read before the work starts, and agents don't read what you didn't tell them to. Put the instruction in the one file the agent loads first:
## Before every task
1. Read LESSONS.md in full.
2. If a lesson applies to this task, say which one in your first message.
3. If you fail at something not covered, add it — cause, not symptom.
Step 2 is the one people skip and it's the one that matters. An agent that says "applying lesson 3, hard cut" is telling you the file is loaded. An agent that says nothing hasn't read it, whatever it claims.
Who writes it
Not you, at least not only. The same agent that did the work, or a reviewer that reads what happened. If you have a QA or reflection step already, the lesson is one of its outputs — that's what makes this a loop instead of another document you maintain by hand.
Common mistakes
- Writing the incident. Two paragraphs about what broke. Nobody reads it twice.
- Writing what you wish had happened. "Be more careful with timings" isn't a rule.
- Letting the file become a to-do list. Open items aren't lessons, and they rot.
- A lesson per agent with no shared file. Then you've rebuilt the problem: five agents each missing four lessons.
- Never deleting. The cap exists to force that decision.
The receipt
Agents that write reflections on their own failures scored 91% pass@1 on HumanEval against 80% for agents that don't (Reflexion, Shinn et al., NeurIPS 2023). Caveat: 2023 models, one agent reflecting on itself — but the mechanism is the one in this guide, and 11 points is not a rounding error.
How to set it up
- Create the file.
LESSONS.mdat the root of whatever project your agent works in. Empty is fine. - Write the three reading rules (above) into the file your agent loads first — its instructions, its
AGENTS.md, its system prompt. - Write the first three lessons yourself, from the last week. If you can't name a cause for one, delete it — that's the filter working.
- Run one task. Watch whether it cites a lesson. If it doesn't, the instruction isn't in the right file.
- Give the writing half to an agent once the reading half is proven. Cap at 1,500 tokens, one line per lesson.
shogo-guide.md next to this file is the version to paste into a Shogo project if you want the whole thing set up in one message.
Next step
Once the file is being read reliably, the next question is who gets which lesson — a lesson about planning shouldn't land on the developer. That's the ROLES guide: the same split, by role, across two models.
Set it up in Shogo
Open a Shogo workspace and paste this into the chat. Answer its questions; the agent builds the rest.
Set up a lessons file for this project, in one pass, and show me it working.
Create `LESSONS.md` at the root with this header and nothing else:
```
# Lessons
One line per lesson. A lesson names a cause, not a symptom. Cap: 40 lines (~1,500 tokens).
When the file is full, merge or delete — never raise the cap.
## Before every task
1. Read this file in full.
2. If a lesson applies to this task, say which one in your first message.
3. If you fail at something this file doesn't cover, add it — cause, not symptom.
```
Then add a rule to `AGENTS.md` (create it if it doesn't exist) under a `## Before every task` heading:
"Read LESSONS.md in full before starting. Cite the lesson that applies. Add a lesson only when the cause is known."
Then do the part that proves it. Read the git log and any bug-fix or review notes in this repo from the last 14 days, and write **three real lessons** from them into `LESSONS.md`, following these tests:
1. It names a cause, not a symptom. "The test was flaky" fails. "The test asserted on a timestamp that the fixture wrote in local time" passes.
2. It says where in the pipeline the cause lived — the plan, the docs, the config, or a judgement call.
3. It names the file or step that owns the fix, so the lesson has an owner.
Do not invent incidents. If you can only find two real ones from the repo, write two and tell me what you looked at and what was missing. Do not write generic advice like "write more tests" — if it would apply to every project on earth, it isn't a lesson from this one.
Finish by replying with: the three lessons you wrote, the evidence for each (commit, file, or note), and the token count of `LESSONS.md`.