In my last post, I described how a small agile or startup project can have low cognitive debt (where everyone has a good understanding about the goals of the project and what we are doing) but high intent debt (nothing is documented for future team members or agents to refer to). I used the analogy of a missing stop sign to describe this situation: the locals know what to do, but human or agentic visitors from out of town do not.
But there is also an opposite failure mode! Sometimes the signs are all there, but understanding is not.
The signs are there, but are hard to understand
We have probably all experienced driving in an unfamiliar area or country and feeling overwhelmed by the sheer number of signs. The important sign we needed was hidden by other signs, appeared too early or too late in our journey, or we lacked the context to interpret it correctly. Software projects may suffer from a similar problem.
Many projects have low intent debt: user goals, decisions, specifications, architecture diagrams, and design rationales are all carefully documented. Yet they can still have high cognitive debt because that information is difficult to navigate, lacks context, or fails to help developers build a coherent mental model of the system.
In theory, if everything is recorded, a future developer (or our future self!) should be able to reconstruct the necessary understanding by reading the available artifacts. In practice, this rarely works. Artifacts are often fragmented across tools and documents. The signs are there, but we don’t know how to navigate them.
Traditionally, capturing intent documentation has been difficult and tedious, but AI is making this much easier (perhaps even too easy). We now have numerous frameworks and tools that can record decisions, generate documentation, summarize discussions, and articulate rationale. But understanding does not emerge simply because information exists.
As Arty Starr recently argued in her post on software as activity rather than artifact, the value of documentation comes from how well it supports the activity of software development. Developers need the right information at the right moment to help them orient, decide, create, validate, and troubleshoot.
Mental models take time, effort, engagement, and experience to build. The many signs at the unfamiliar intersection that stumped us the first time we encountered them will become easier to interpret after we have driven through it a few times. Likewise, understanding of a system comes from our interactions with the system, not simply reading information about it.
Road designers also need to learn from drivers which signs are redundant and which ones caused confusion by where they were placed or worded. Good signage evolves from understanding drivers’ needs, not just from changes to the roads themselves.
(Re)Building understanding
Software development is a dynamic activity, and software that is useful will evolve. Our understanding of the system must evolve alongside it.
Even if the documentation were somehow “perfect”, it will not be enough to build understanding on its own. We need practices and tools that help developers navigate across layers of artifacts, connect information together, and help us find the right information at the right time.
This need is one of the motivations behind the Cognitive Tours tool I’m building (more on this in the next couple of weeks). I also see a growing number of tools and approaches emerging that recognize the same challenge.
Capturing intent is important. But helping people navigate and build understanding may be even more important.
More Reading
- Triple Debt paper, ACM Queue, May 2026 paper link
- Addy Osmani blog post that reflects on Intent Debt in Practice
- Arty Starr blogpost on Software as Activity Instead of Artifact
- Troubleshooting as Activity (Starr & Storey, 2026) paper link
- Cognitive Tours post
- The Missing Stop Sign: Why a Project May Have High Intent Debt and Low Cognitive Debt blogpost