Cognitive tours help teams keep software understanding clear
Cognitive Tours: Making Understanding a Deliverable in AI-Assisted Development
Software Engineering
Summary
Software projects can become hard to understand over time, even if the code is fine. The authors identify two problems: cognitive debt, where no one on the team fully understands the system, and intent debt, where the goals and reasons behind the software aren’t clear. They created a tool called Cognitive Tours that helps teams document and link together user needs, design choices, and code in a way that AI can assist with but humans guide. This tool helps teams share knowledge and maintain clarity about how and why software works.
What this means in practice
- •For software development teams: Document and share clear explanations linking user needs, design decisions, and code to reduce misunderstandings and improve maintenance.
- •For software project managers: Use AI-assisted tours to routinely audit system knowledge and update documentation, helping to manage risks from unclear goals or team understanding.
Authors
Margaret-Anne Storey
Abstract
Generative AI and agentic coding are accelerating software development, leading to concerns about technical debt. But two less visible forms of debt, cognitive debt and intent debt, are emerging as key risks to software health. Cognitive debt is the absence or erosion of a team's shared understanding where no one can confidently explain how a system works or predict the impact of a change. Intent debt is the lack of clearly articulated goals, constraints, and rationale that explain what the system is for and guide how it should evolve. This paper presents Cognitive Tours, a tool designed to mitigate and repair cognitive and intent debt. Cognitive Tours is a web-based prototype for creating and following curated paths connecting user needs, design decisions, code, tests, and open questions. AI-assisted skills help audit existing waypoints and tours for possible problems or staleness and suggest candidates for new ones; humans decide what matters, verify relationships, and construct the narrative. This division of work deliberately preserves productive friction: the sensemaking involved in selecting, explaining, and revising a tour, which is intended to foster and share understanding. Our demonstration uses a tour of Cognitive Tours itself to introduce the tool and illustrate its design decisions and interaction mechanisms. A proposed evaluation agenda concludes the paper. A demo is available at https://cognitive-tours-demo.vercel.app/