Answer in brief
Writing a lesson down will not stop you repeating a mistake. A note only works if you remember to read it. Remembering is the thing that failed the first time. So build something that makes the mistake impossible. Then check that you actually use it. Building a tool and using it are two separate events, and you only see the first one.
What went wrong, twice
Some mistakes come back. The second time is the one worth studying, because by then you thought you had fixed it.
I run a small team of AI agents. One of them reads notes out of my vault, which is the folder of notes my agents read and write. Each note starts with a few labeled lines, such as the author or the date. Each labeled line is a field.
To read one field, the agent used a rule for finding text. The rule had a flaw: when a field was left blank, it did not stop at the blank line. It ran on and picked up the value from the line below, the way you might copy the wrong answer off a form when someone leaves a box empty. So on a batch of files that were actually fine, the agent reported a problem that was not there.
empty field -> rule runs past line end -> grabs next line's value -> [BROKEN] false report fix: shared reader + tests -> used in 3 scripts only
The agent caught the error and took the report back. It wrote the lesson into its own memory in plain terms: this rule crosses lines, so do not use it for a single field.
Two hours later it wrote the same rule again. It was new code, reading the same field. It got the same wrong answer.
The lesson so far: a written lesson did not change what the agent did two hours later.
What the agent did about it
The agent stopped and built a small shared reader. A shared reader is one function that every script can call to read a field. It came with a test for every version of the bug that had shipped that day, including the empty field that picked up its neighbor. The tests ran before the reader was used for anything.
Then the agent used the reader to redo a count it had already sent. The reader disagreed. The count had gone out as ten. The real figure was fourteen. The earlier hand written rule had missed one of the two forms the vault uses, and the reader handled both.
Here is the part worth keeping. A fix built after a repeat failure caught a real mistake the first time it ran. It also came one report too late. That count had already gone out as a finished answer, reported as correct, and a fix cannot pull back what has already shipped.
What the day-gate verdict found a day later
A day later, at the day gate, the agent checked how often the reader had been used.
Three scripts. The agent had written several other scripts that same evening. In those, it had hand written the same fragile rule the reader was built to replace. It did not disagree with the reader. The reader was not missing anything. The agent simply did not reach for it.
The reader works. A day later its tests still passed. It still reads correctly after a large batch of files was renamed underneath it. And the bug it exists to prevent survives, untouched, in every script that does not call it.
What I take from it
A tool is not a habit. Writing the rule down felt like solving the problem. Building the tool felt like solving it more. Neither one changed behavior on the day.
A second point is easier to miss. Once a shared fix exists, people read its existence as the problem being solved. Anyone looking at that agent now sees a reader with tests. They conclude the bug is handled. It is handled only in the scripts that call the reader. The other scripts look the same as before, and now they are harder to spot.
So the note that matters is not in the tool. It sits in the written rules for that code. It says that a hand written version of this rule, anywhere, is a defect for a reviewer to catch. The tool cannot enforce its own use. A person looking for it can.
What I would tell someone starting out
Write the lesson down anyway. It is not useless. It is just not enough on its own, and you will need it when you build the real fix.
Then do the part almost nobody does. A few days later, count how many places use the thing you built. That number is the only honest measure of whether you fixed anything. Expect it to be lower than you think.