Route the lesson, don’t repeat it

Here is a pattern you have almost certainly seen. A reviewer catches something on a pull request. It gets discussed, fixed, and the thread is resolved. Somebody sensible writes a note on the ticket so it is not forgotten. The work merges.

Six weeks later the same thing happens on a different ticket, written by a different person, and the note that would have prevented it is sitting on a piece of work nobody has any reason to open again. Nothing was careless. The lesson was genuinely captured. It just had no way of reaching the next person who needed it.

I think the problem is that we treat capturing a lesson as the goal, when capture is the cheap half. The decision that matters is where the lesson lands, and it is almost never made deliberately.

A ladder, with four rungs

When a finding appears, there are usually four places it could go. They are not equally good, and they are in this order for a reason:

1. Build tooling, or a gate in CI. A check that fails, a coverage threshold, a lint rule, a hook. Nobody has to remember it and nobody can skip it by being in a hurry.
2. Repo conventions. A written rule in the place where people (or agents) look for how this codebase does things. Requires reading, but is written once and applies everywhere.
3. The templates that produce the work. If a spec keeps missing the same question, the fix belongs in the thing that generates specs, not in the spec.
4. This one piece of work. Genuinely one-off. The last resort.

The rule is to always take the highest rung that could prevent recurrence automatically, and to fall down the ladder only when you have to.

One question to choose

The test I use fits in a sentence: would this instruction get copy-pasted into many future tickets?

If the answer is yes, it does not belong on a ticket at all. “Remember to add tests for the error path” is not a note, it is a coverage gate wearing a note’s clothing. “Use the repository pattern for data access here” is not a review comment, it is a convention that someone has not written down yet. Every time you write the same advice a second time, you are paying interest on a decision you did not make the first time.

Why the bottom rung wins anyway

Nobody disagrees with any of this, and teams still put almost everything on the bottom rung. The reason is not ignorance, it is cost at the moment of the decision.

Writing a comment on a ticket takes ten seconds and requires no permission. Changing a CI gate means touching shared configuration, thinking about whether it fails other people’s builds, and probably a conversation. Changing a template means having an opinion in public about how everyone works. At the exact moment you are holding a small fresh lesson, the cheap option is right there and the valuable one requires energy you have just spent on the actual work.

So the leverage is not in convincing people that gates are better than comments. They know. It is in making the higher rungs cheap at the moment the evidence is fresh — which usually means having the concrete proposed change already written, so the decision is “yes or no” rather than “go and do it”.

Exactly one destination

One more discipline, and it is the one people push back on: each finding goes to exactly one place. Not the gate and the convention and a note on the ticket, in case.

Filing it everywhere feels thorough and is corrosive. It produces conventions documents restating what CI already enforces, and tickets full of advice that is already a rule, and the more of that accumulates the less anyone believes any of it. A convention nobody needs to read teaches people that conventions are not worth reading. Choosing one destination is what keeps each layer meaningful.

What I actually know

I built this into a tool that runs on my own work: when a pull request merges, an agent reconstructs what was asked, what shipped, and everything reviewers had to catch, and routes each finding down this ladder. That is written up in a case study, honestly labelled as the timeboxed spike it is.

What I cannot yet tell you is whether it works. I have not measured whether routing a lesson upward actually reduces recurrence — that needs more findings and more time than I have given it. So take the ladder as a way of thinking rather than as a result. The part I am confident about is the diagnosis: teams do capture lessons, the lessons mostly land on the lowest rung, and the reason is that at the moment of decision the lowest rung is the cheapest thing in reach.