# The Intent Debt: Why Teams Lose Track of Why Systems Exist
Most teams understand technical debt. Code accumulates shortcuts. Performance degrades. Bugs multiply. The problem sits there in plain sight, waiting to be fixed.
Intent debt operates differently. It lives nowhere visible. It hides in the gaps between what exists and why it exists.
Addy Osmani, writing on his blog and republished through O'Reilly Radar, identifies a category of organizational debt that teams rarely acknowledge: the missing or deteriorating record of decisions that shaped a system. Intent debt accumulates when goals fade from memory, constraints go unrecorded, and rationale vanishes alongside the engineers who made original choices.
This matters because systems inherit their design from decisions made months or years prior. A database schema reflects tradeoffs between consistency and scale. An API endpoint's rate limiting responds to past capacity problems. A feature flag sits dormant because it solved a problem that no longer exists. Yet if no one wrote down why these choices happened, new team members rebuild their understanding from scratch. Worse, they rebuild it incorrectly.
The cost appears gradually. A junior engineer deletes a "legacy" field that once supported an important workflow, unaware it still feeds a quarterly report. A platform team refactors an internal tool without realizing it prevents a critical integration. A database migration proceeds without knowing why the original schema chose eventual consistency over atomicity. Each incident traces back to the same root cause: no one captured the intent.
Technical debt gets easier to spot. A linter flags it. Performance metrics show it. Pull request review catches some of it. Intent debt leaves no trace. It only emerges when someone makes the wrong decision because they lack context.
The solution requires shifting how teams document work. Osmani points to the gap between cognitive debt, which lives in people's heads, and intent debt, which lives in artifacts that may never have been written at all. One person knows why a system looks like it does. They carry that knowledge in their head. When they leave, the knowledge leaves with them.
Documentation habits fail here because standard documentation captures what a system does, not why it does it. Comments explain code logic, not architectural decisions. Commit messages describe changes, not the constraints that shaped them. Runbooks describe how to operate systems, not the tradeoff analysis behind their design.
Teams that manage intent debt well treat decision rationale as a first-class artifact. They record not just what they built, but the goals they optimized for, the constraints they faced, and the alternatives they rejected. They treat this record as part of the system itself, not an afterthought.
This becomes more pressing as teams grow, onboard remotely, or experience turnover. The larger the gap between decision makers and system operators, the more intent debt accumulates. A five-person startup where everyone was present at design discussions lives comfortably without it. A distributed team of fifty engineers maintaining code written years earlier drowns in it.
The practical consequence is clear: teams spend time rediscovering decisions they already made. They rebuild understanding incrementally through production incidents. They optimize systems based on outdated assumptions. They refactor based on hunches rather than evidence.
Addressing intent debt early costs less than excavating it later. The work looks like adding decision logs to architecture review processes, capturing constraints in design documents, and treating intent documentation as part of code review standards. It feels like overhead until the day a new team member needs to understand why the system is the way it is.