The Archaeology Tax

Somewhere in your organization right now, a senior engineer is spending two weeks learning something your organization already knew.

Not learning it for the first time. Re-learning it. The knowledge existed once, in the heads of the team that built the system and in the hundred small decisions that shaped it. The organization paid full price for that understanding. Then the people moved on, the documents drifted, and the understanding quietly left the books. Now a change has to be made, and someone has to buy it all back.

Let’s call this the Archaeology Tax: the recurring cost of re-excavating understanding you already paid for. You won’t find it on your scrum board, because we book it as something else. We book it as “ramp-up.” We book it as “discovery.” Mostly we book it as a change that came in at three times its estimate.

Two Weeks Before the First Line of Code

Consider the problem of changing a system nobody fully remembers.

A mid-sized company runs a billing engine at the center of everything: eight years of accumulated pricing rules, discounts, and regulatory carve-outs. A new market launch needs one rule changed. On the roadmap it’s a small item.

Four people built the engine. Two have left the company. One got reorged into a different division and now answers messages a day late, with fading detail. The fourth is still around, but he’s shipped three systems since, and his memory of this one has blended into all of them: which engine had the rounding quirk, which queue fed which service, whose retry logic did that one strange thing.

So a senior engineer gets borrowed from feature work and starts digging. The architecture page in the wiki is four years stale and describes a message queue that was replaced eighteen months ago. There are two runbooks. They disagree with each other, and the code disagrees with both. Git history should help, but the commit messages are hasty fragments and laundry lists (“fix edge case for legacy tier,” no ticket link, author long gone). The test suite turns out to be the best source in the building: hundreds of precise assertions about what the engine must do. Still shots, though. No narrative. He interviews the reorged engineer twice. Eventually he builds a small harness just to watch what the engine actually does with boundary inputs, because by now the code’s behavior is the only source he trusts.

Day eleven: he writes the first line of the actual change. The change takes two days. Thirteen days on the books, eleven of them excavation. The estimate absorbed the digging without ever naming it. That’s the tax: priced into every “small” change.

And notice where all that hard-won understanding ended up: in one person’s memory, the most volatile storage there is. (Some notes made it into the wiki, next to the three versions of the truth already there.) Eleven days of effort for this fleeting moment of change, and then once again slowly lost to time and the sea of stuff.

An Unbooked Liability

Lose a machine and the loss shows up on the books: an asset was there, now it isn’t. Lose understanding and nothing shows up anywhere. There is no ledger for institutional knowledge, so there’s no write-down when it walks out the door. The cost surfaces later, laundered through symptoms: estimates that balloon, “quick” changes that take a month, senior engineers working as human search engines.

This is the second face of the problem Part 1 opened. There, the trouble was the Empty Chair: the job no team staffs to overcome the natural entropy of institutional knowledge, so the durable path kept losing, fork after fork, for want of a worker. That was the vacancy; the Archaeology Tax is its invoice, what the entropy costs once someone has to change a system the company no longer understands. The Chair stood at the moment of the work; the Tax arrives at the reckoning, months or years later.

How big is the tax? Stripe’s Developer Coefficient report put developer time lost to technical debt and bad code at around 42 percent of the work week¹ (self-reported survey research, so take it directionally). Field studies that instrument the actual workday put it higher: one tracked 78 professional developers across more than three thousand working hours and found program comprehension consuming roughly 58 percent of their time.² Whether the true number at your shop is forty percent or sixty barely matters. What matters is the magnitude: something like half of engineering capacity goes not to building, but to understanding what’s already built. We optimize hiring, tooling, and process around the building. That second job, which costs about as much, has no owner, no metric, and no line item.

In fairness, some of the digging is unavoidable. Old systems hold tacit knowledge no document ever captured: why one approach was chosen over another, what was tried and abandoned. And a fresh dig sometimes produces something the original team never had. Our engineer, for one, walked away with a boundary-input harness no one had built before. The goal isn’t zero archaeology. It’s to stop paying full price, again and again, for understanding the company captured once and then let rot.

We Filed It Under Physics

The rate of decay only moves one way. This is knowledge entropy in motion: every departure, acquisition, and reorg disperses what the company knows a little further, and nothing gathers it back. None of that is news; anyone who has run an engineering group has watched it happen. Somewhere along the way, we collectively decided this is just physics. We pad the estimates, budget the ramp-up, hire ahead of attrition, and cope. We stopped asking whether the dispersal could be reversed, and acceptance hardened into strategy. Keep that assumption in view. It’s the one this series intends to break.

Tests Used to Decay Too

The standard response is the one every organization has already tried: document more. Part 1 covered why that disappoints (knowledge has a half-life; documents are snapshots of a system that keeps moving). Further complicating the matter is the difference in lifecycle between code and docs. Code lives in the repository, where a change is driven through the quality gates of review and tests until they pass. Whereas documentation lives somewhere else (a wiki, a portal, a shared drive), where a change only takes place when someone remembers it exists, feels responsible for it, and has time to attend to it. There’s no enforcement to make sure the updates happen, so they rarely do.

So documents drift. And drift is worse than absence. An absent document sends you to the code with your skepticism intact. A stale document is an authoritative-looking account of a system that no longer exists. Our engineer lost real days to sources that were wrong with confidence. The wiki didn’t fail to help him; it taxed him.

We have cured this exact disease before. Not long ago, tests had the same symptoms documentation has now. They lived apart from the code, in a suite owned by a separate team, run on a separate schedule. They described the system as it stood when they were written. They drifted. Keeping tests in sync was a discipline that required tremendous effort and often resulted in drift anyway.

What fixed it wasn’t a better mandate. Tests moved into the repository, next to the code they describe, running with every build. Tests can still be skipped, still go flaky, still get quietly deleted; but a test that’s wrong about the system now fails loudly, in everyone’s pipeline, and demands a decision. Decay went from silent to visible, and visible decay gets dealt with. Architecture did what discipline alone couldn’t.

Documentation needs to make the same move. Into the code, onto the same lifecycle, able to fail the build when it stops being true. A test can fail; a paragraph can’t. Yet. What stands in the way is scale: keeping every paragraph true through every merge is a superhuman task. How it stops being superhuman is where this series is headed.

The Tax Notice

The Archaeology Tax is real, large, and unbooked. You pay it in inflated estimates, slow “small” changes, and senior engineers doing spadework. Every departure, acquisition, and reorg raises the rate. Treating that as unchangeable is a choice, not a fact.

Drift is worse than absence. A stale document taxes the reader twice: once to trust it, once to discover it lied. Counting pages written measures the wrong thing.

The destination is documentation that lives where tests went: in the code, on the same lifecycle, failing loudly when it stops being true. Today that’s a superhuman ask. It won’t stay one.

A principle for the pivot: Build documentation that can fail over documentation that can lie.

Next in the series: what happens when a carefully written procedure meets a world that changed after it was written, and what that says about the paradigm underneath: The Clockwork Assumption.

---

About this series: Next Quarter’s Normal is about how agentic systems are changing the way we build software. Today, though, we mostly apply agentic capability to assist our current practices. Useful, but not the point. The deeper opportunity sits in the problems we long ago filed under unsolvable, and in ways of working we haven’t imagined yet. We still build our tooling around the individual developer, when the heavy lift is getting an entire community to work in harmony. I don’t claim to have the answers; I’ve been building, and finding out. So each article closes by nominating one principle for the pivot: Waterfall to Agile took a re-imagination, and Agile to Agentic will too.

Footnotes

1. Stripe, The Developer Coefficient, September 2018. Self-reported survey research, so directional: technical debt (13.5 hrs/wk) plus bad code (3.8 hrs/wk) of a 41.1-hour week works out to about 42 percent; broader maintenance runs to roughly 20.9 hrs/wk. https://stripe.com/files/reports/the-developer-coefficient.pdf ↩

2. Xia, Bao, Lo, Xing, Hassan, and Li, Measuring Program Comprehension: A Large-Scale Field Study with Professionals, IEEE Transactions on Software Engineering, 2018. 78 professional developers, 3,148 working hours, about 58 percent of time on program comprehension. https://ieeexplore.ieee.org/document/8453126 ↩