Switching agencies without losing six months.

The story arrives in a predictable shape. A company changes development partners, for good reasons, and then loses half a year. Not to a contract dispute or a botched repository transfer, but to something quieter: the new team opens the codebase and has no idea what it does. So they spend months doing archaeology, reading code to infer intent, breaking things to discover what depended on them, rebuilding in their own heads a map that the previous team had in theirs and took with them out the door.

The expensive thing you lost in the switch was never the code. The code transferred fine. What didn’t transfer was the understanding of what the code does and why, and that’s the asset that actually runs your business. The market has started calling this comprehension debt, a term Addy Osmani used in early 2026 to name the gap between code that exists and code anyone can account for. A team handoff is the moment that debt comes due all at once.

Here’s the part worth sitting with: the understanding walked out because it was never written down in a form that could stay. It lived in standups and Slack threads and the particular engineer who remembered why the retry logic was the way it was. None of that is portable. A new team can’t inherit a memory. They can only inherit artifacts, and if the only artifact is the source code itself, then “reading the code” is the handoff, and reading the code at the speed of comprehension is exactly the six months you’re trying not to lose.

The artifact that transfers

What makes a handoff cheap is an artifact that carries the understanding instead of the understanding living in people. A behavior catalog is that artifact: a typed inventory of every observable behavior in the system, each entry cited to the file and line that produces it. A new team reading a catalog isn’t inferring intent from implementation; they’re reading a map that says, in checkable form, what the system does and where each behavior lives. The provenance is the trust mechanism. A gate greps each citation out of the source, so the catalog can’t drift into fiction the way documentation always does. It either matches the code or it fails the build.

A catalog is portable in a way knowledge in heads never is. It survives the people who wrote it. That’s the whole point. When the question is “how do we switch teams without losing six months,” the answer is to make sure the thing that takes six months to rebuild, the understanding, exists outside anyone’s head before the switch happens.

Do this before you leave, not after

The practical sequence matters, and most people get it backward. The instinct is to switch first and sort out the mess later, which guarantees the archaeology. The better move is to run a verification audit of the current system while you still have access to whoever built it, even if you’ve already decided to leave. The audit produces the catalog, the coverage-debt report, and the regression tests the system never had. That bundle is institutional memory made portable, and it’s worth more at the moment of a transition than at any other time, because it’s the difference between handing the next team a map and handing them a maze.

We’ve been the new team walking into an unfamiliar codebase, and we’ve felt the pull to just start rewriting, because rewriting feels like progress and reading feels like delay. It’s a trap. The rewrite that skips comprehension reproduces the original sin: it builds a new system nobody can account for, and sets up the next painful switch. The way out of the cycle isn’t a better team. It’s making the system legible, once, in a form that the next team, whoever they are, can actually inherit.