How Tacit Knowledge Travels

Humans pick up a team's knowledge over years. An AI agent gets one context window. Specs are how the knowledge makes the trip.

To someone writing assembly code, the Python coder looked like a fraud: fast, capable, and missing something real about the machine underneath. John Price, building on a point from Brian Deters, argues this has happened at every layer. Every tool that made programming easier also let in newcomers who didn't know what the old-timers knew.

The field always adjusted. It just never wrote down how.

The adjustment was apprenticeship. The newcomer sat near the masters. Knowledge moved through code review, hallway corrections, and watching someone debug at 2 a.m. Apprentice, journeyman, master: the way every craft has handed itself down for centuries. This is what tacit knowledge means: the stuff everyone on the team knows but nobody wrote down. It never lived in the documents. It lived in the team, and it moved the slow way, over years.

That worked because apprentices had years.

The newest arrivals don't. An AI agent joining your codebase gets no bench next to a master and no hallway. Everything it will ever know about your intent is what you hand it, this session, inside one context window. It's the first apprentice in the history of the field that can't learn the slow way. It can only be handed things.

Specs are how tacit knowledge travels.

That's why specs came back. Not nostalgia. Not because AI can't be trusted. Specs are back because, for the first time, the knowledge has to ship as cargo. The spec is the container.

Which changes what a spec has to be. A spec written for a colleague can be loose, because the colleague fills the gaps from shared experience. A spec written as cargo can't assume anything. It has to say what the work is for. It needs an ID that survives being handled by many hands and many sessions. And it has to stay checkable after it arrives: did what was asked for get built, and where's the proof?

That's the same thread the first three notes describe, seen from the other end. A durable ID isn't paperwork. It's a handle on a piece of knowledge, so the knowledge arrives intact and can answer questions when it gets there.

The economics used to point the other way. Writing knowledge down so carefully cost more than letting people learn slowly... so much more that only regulated industries paid for it. AI flipped both sides at once: it created the apprentice who can't learn slowly, and it made careful writing cheap. Same tools, both directions.

And the human apprentices? They're rightly worried there will be no seat left for them. History says otherwise: the same fear showed up when compilers arrived, and every layer since has ended with more programmers, not fewer. But there's a nearer reason for hope. A spec written as cargo doesn't only feed agents. It hands a new human the same thing it hands the machine: the team's knowledge, written down, on day one. What used to take years of sitting near the masters now arrives with the work. The ladder didn't disappear. The first rung just got closer to the ground.

Teams that treat specs as paperwork will keep getting work that looks right and traces to nothing. Teams that treat specs as cargo will find their apprentices, human and machine alike, show up already knowing where the work came from.

Monday morning

Ask a new hire, or a fresh agent session, one question about your codebase that everyone on the team knows the answer to. Watch where they go looking. That's your tacit knowledge, and its travel route.
Write that one answer down in the spec it belongs to. One paragraph. You've just shipped your first piece of cargo.
Give every intent an ID that survives handling. A spec written as cargo can't rely on shared memory to fill the gaps.
Make the spec answer "what is this for?" before it says how. The why is the part apprentices used to absorb by osmosis.
Hand the next human apprentice the same spec you hand the agent. Then notice how much less you have to explain.

Specs are how tacit knowledge travels. SpecAssay is how you check that it arrived.

Footnote: in 1997, a Palo Alto company literally named Tacit Knowledge Systems attacked this same problem from the other side. Its product read everyone's email to detect who knew what, because getting people to write knowledge down was too expensive. Oracle bought it in 2008 and it vanished. The problem has been real the whole time. The economics just hadn't flipped till now.