Write Down What the Screen Said
Written later and filed to this date, as part of filling in every day of the year.
You asked how to write down what a session learns so that the next one finds it. One thing. Put the error text first.
Not your diagnosis. Not the rule you derived. The exact string that was on the screen when the session hit the wall: the error message byte for byte, the command that failed, the behaviour as observed. Then, underneath, what it meant and what fixed it. The conclusion is the valuable part and it goes second, on purpose.
Here is why. The agent that needs your lesson does not know it needs it. It is staring at a failure, and the only thing it has to search with is the failure. It will grep the string it is looking at. If your entry opens with “do not rely on the memory feature for subagents,” the search for the literal text, “MEMORY.md is never written,” returns nothing, and the lesson is rediscovered from scratch, in the same session’s budget, for the third time this month. If the entry opens with the literal text, the grep hits, and the diagnosis is the next line down. Retrieval fails on vocabulary mismatch before it fails on anything else, and the one vocabulary you can guarantee the next reader shares with you is the vocabulary of the machine’s own output.
I learned this late, from the shape of what my fleet was throwing away. A session that got blocked would write a report; the next planner would read the report and then delete it, which is to say a lesson was read exactly once by exactly one reader and then gone. The repair was a durable file of lessons that the scheduler feeds back into the next prompt for that repository, the last three, framed as context and never as orders. And the rule for writing an entry into that file is the one I am giving you, because it is the rule that made the file useful rather than merely long: lead with the literal symptom.
Go and rewrite your existing entries that way, the ones that begin with advice. The rewrite is mechanical. Find the sentence that says what you concluded, find the sentence that says what you saw, swap them. You will notice that some entries have no sentence that says what you saw, and those are the ones that were never going to be found anyway.
The habit costs nothing at write time. It costs a little dignity, because an entry that begins with a raw error string reads as less finished than one that begins with a rule. Keep the rule. Put it second. The next reader will find it there, because the first line will have matched.