The institutional knowledge engineering teams lose is never the code

Something I keep chewing on after onboarding two people this year.

Our conventions are in better shape than they have ever been. Linters, formatters, templates for new services, a review layer on every PR. A new hire absorbs the house style in about a week now and nobody has to sit with them to do it. That part is genuinely solved, and it used to be most of what onboarding actually meant.

The reasoning has not moved at all.

We pulled out a caching layer about eighteen months ago. There is no trace of that decision anywhere. The code that replaced it looks arbitrary unless you happen to know the cache was invalidating correctly, but the invalidation was fanning out across three services and we could not reason about the ordering under load. That explanation lives in two people's heads and one of them left in february.

So a new engineer reads the current code, sees something that looks like it should obviously be cached, and proposes caching it. None of our conventions stop him, because there is nothing unconventional about the proposal. It is just wrong, for a reason nobody wrote down.

ADRs are the obvious answer and yes, I know. We have nine of them, all from a two week stretch in 2024 when someone was briefly enthusiastic. Nobody ever wrote the tenth.

What I have started to think is that the decisions worth recording never feel important on the day you make them. The caching thing was a tuesday afternoon conversation between three people at a whiteboard. It only turned into institutional knowledge in retrospect, and by then nobody remembers it happened, let alone that it should have been written up