Last time I argued that legacy is what happens when the mental theory of a system walks out the door with the people who built it. That post was to create awareness. This one is about what to do once you’re aware.
Two ways to react
The easy way out is to shrug, lean harder on AI, keep teams isolated and deal with the legacy later. It feels productive right up until the theory is gone and nobody can change the system with any confidence.
The other way is to take the whole system seriously. Not just the code, but the people building it and the people living with it. A system stays changeable only while a living theory of it stays in the team. How do we keep that theory alive?
We already know how to do this
Good news first: we are not starting from scratch. I have watched this fail on some teams and click on others, and the difference was almost always shared experience. Pairing, mobbing, collaborative modeling, TDD ping-pong. These are the same practices the previous post tied back to Naur. When I read Naur’s work, it made it obvious why they work. Theory spreads person to person, not page to page.
But the techniques of which I know they work, all heavily lean on co-located teams with high-bandwidth contact, and post-COVID that is no longer a given. That got me wondering… what else could work?
So I asked AI, then argued with it
When you have a question like that today, you ask AI. So I did. I did not want three safe suggestions, I asked for at least thirty ways to build and keep tacit knowledge alive.
Then I gave the output a hard, critical look, because it had real bias and gaps. A lot of proven techniques I already trust were missing, so I made it add those back in. And to make this usable instead of a wall of text, I had it score every method on how well it actually sustains tacit knowledge.
The honest caveat: AI invented a chunk of these and I cannot promise they hold up in practice. But the high-scoring ones are mostly existing, proven techniques, links included. The rest are hypotheses worth trying.
What about AI itself?
A handful of the methods are about using AI to sustain the theory rather than erode it. Right now they score low, which fits what I would expect this early. I do not think that is the ceiling though. These tools have more to offer here than the way we use them today… another option to explore more deeply.
Go explore them
I have already been trying a few of these.
- Knowledge Heat Maps: for this one I built a script that creates a knowledge risk heatmap from git history. I’ll share the script in a future post.
- Theory Debt Standups: we did this with the team recently. Very simple format, yet it surfaced some surprising insights. I’m also planning a post on this one.
Keep an eye on the blog here, I’ll write separate posts for each with more details.
I also want you to start experimenting with ways to actively keep the mental theory on the team alive. I built an interactive page where you can browse and sort each of the techniques by how well they score to sustain tacit knowledge. This is an early iteration and I genuinely want your feedback. I am not going to walk through all the methods here. The point is for you to poke at the tool. Try them out, and let me know what works and what doesn’t. Or maybe you know a technique that needs to be added, don’t hesitate to tell me.
So go and explore these techniques for Theory Building
