Cognitive Tours: Making Understanding a Deliverable in AI-Assisted Development

Cognitive Tours: Making Understanding a Deliverable in AI-Assisted Development Margaret-Anne Storey

arXiv:2611.08456v1 [cs.SE] 5 Nov 2026

Department of Computer Science University of Victoria, Canada mstorey@uvic.ca

Furthermore, the why behind many of the decisions developers make is often not found in the source code (e.g., discarded ideas) and both humans and agents struggle to understand invisible but critical design decisions.

Abstract—Generative AI and agentic development 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 absence 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. Index Terms—program comprehension, AI-assisted development, cognitive debt, software intent, code tours.

The triple debt model of software health draws attention to two concerns beyond technical debt: cognitive debt, the absence or erosion of the shared understanding needed to work with a system, and intent debt, the loss or absence of explicit goals, constraints, and rationale [1]. A program may be technically sound and of high quality, but be difficult for its maintainers to explain or know how it can be safely evolved. Furthermore, a working and plausible implementation may not satisfy a requirement that was never adequately articulated or externalized. Cognitive Tours provides a mechanism for developers relying on AI and/or agents to hand craft curated journeys through the reasons, decisions, implementation, evidence, and uncertainties that help tell the story behind a feature or task. The intended user of these tours is not only a newcomer onboarding to unfamiliar code, but also the developer themselves who must later make changes to the system and recapture forgotten decisions and assumptions.

I. I NTRODUCTION Generative AI and agentic development are accelerating software development, allowing individuals and teams to generate and modify code faster than ever before. But many developers and teams are sharing how they struggle to keep track of the work they are doing and answer questions about the reason for its design, the constraints it must satisfy and how the system can evolve to meet future requirements and changes [1]. Cognitive debt is held by a team, not only an individual: when the reasoning behind a change lives in one developer’s head or one chat transcript, everyone else on the team, and that developer months later, inherits the gap. Although developers may have access to the code, agent interaction histories and agents to explain how their systems work, developers struggle to maintain understanding and control of their system [2]. Writing and modifying code has traditionally provided opportunities for developers to develop their understanding through implementation decisions and problem solving. Delegating these activities to AI may remove some of those opportunities. Our prior research on troubleshooting [3] and developer momentum [4] describes the cognitive work involved in building up working context to support progress on a task during development with AI.

Tours are human-authored by default, with optional AI drafting that requires human verification. The designer or developer must decide what matters to record and what to omit so that the important information in the tour is salient. AI supports the identification of new candidate and outdated waypoints and tours as the system evolves. The approach is designed to reduce the toil in creating and updating them, but not to automate them fully, which would suppress the understanding they build. This paper demonstrates a web-based prototype through a self-tour: we use a tour of Cognitive Tours to explain the motivation and design of Cognitive Tours. Our contribution is a tool and interaction design proposition, not a validated claim (yet) that tours can reduce or mitigate cognitive or intent debt. However, the tool has been used by the author during its development and provided cognitive support across sessions over six months and exposed a discrepancy between a design decision (captured as an ADR [5]) and a recent implementation choice.

1

II. BACKGROUND AND T OOL P OSITIONING

TABLE I T OOLS THAT CREATE AN ARTIFACT FOR UNDERSTANDING , ON FOUR

Twenty years ago, my colleagues and I introduced the waypoint metaphor for collaborative understanding and software navigation and orientation [6]. The Tours Eclipse plugin combined slides and live IDE navigation for programmer-to-programmer presentations and tours [7]. In this paper, we revisit these design principles and adapt software tours and waypoints to today’s era of AI-assisted development. Our earlier attempt saw barriers to adoption due to challenges maintaining waypoints and tours as the software changed over time. Today, this toil can be mitigated through the use of AI and agent skills to help developers keep waypoints and tours up to date but preserve how creating them helps enrich understanding. The use of AI is limited to scaffolding while the developer is responsible for understanding. Recent work has explored the potential value of guided code exploration. Horvath [8] studies how developers’ thoughts, questions, design rationale, and development traces can be externalized as meta-information to support subsequent sensemaking. Cognitive Tours shares this emphasis on preserving developer reasoning, organizing it into human curated paths that connect intent, decisions, features, user needs, implementation, and tests. Taylor and Clarke studied Microsoft CodeTour, manually creating two annotated CodeTours, studying its potential for orientation and navigation [9]. LACY combines AI-generated content with expert-curated code tours, comprehension questions, and other onboarding support [10]. Its evaluation shows promising evidence for expert-guided onboarding. CodeMap similarly explores human–AI collaboration and uses AI to dynamically generate hierarchical visualizations for exploring unfamiliar codebases [11]. Cognitive Tours differs from CodeTour, LACY and CodeMap in its application beyond code artifacts to design and intent artifacts, and its allocation of cognitive work. Another recent tool, Bram1 , preserves agent-work sessions, human approvals, and associated development history. Bram further provides AI-generated orientation diagrams of a repository’s architecture. Cognitive Tours complements Bram’s approach by helping developers construct and maintain an explicit account of software intent and understanding. Romeo et al. [12] also investigate drift between software design, implementation, and documentation, using links between UML diagrams and source code to identify inconsistencies as systems evolve. Cognitive Tours takes a complementary approach by connecting user needs, design rationale, code, and tests through curated navigation paths, with AI-assisted auditing to identify potentially stale or inconsistent explanations. Balfroid et al. [13] explored LLM-generated code tours based on failing-test traces, finding that automated generation is feasible but can produce redundant and low-level explanations. Going further, AI-generated repository wikis such as DeepWiki2 and Google Code Wiki3 document an entire

DESIGN DIMENSIONS

Tool

When

AI writes What it records

For whom

Spec Kit, Kiro Lattice

before code before, during during

much

requirements, plans

agent

some

team standards, design decisions AI coding conversations

agent

SpecStory

CodeTour [9] after LACY [10] after As-built after architecture Diagnostic during Legibility DeepWiki, after Code Wiki Bram during, after Cognitive Tours

before, during, after

none (a log) none some all

code walkthroughs code tours, quizzes architecture, workflows

team, agent newcomers newcomers people

all

domain concepts, workflows people

all

code documentation

anyone

much; humans approve

proposals, approvals, sessions

team, agent

suggests; goals, needs, rationale, open team, questions, linked to code and author humans curate (AI tests drafts optional)

codebase automatically, with no developer authoring. Cognitive Tours instead uses AI to support discovery and maintenance while keeping developers responsible for the explanations and rationale. These tools differ along at least four design dimensions (see Table I): when an account of the software is constructed, how much of it AI writes, what it records, and for whom. They range from spec-driven tools that record intent before code is generated (GitHub Spec Kit4 , Kiro5 ), through tools that give the agent context or record work as it happens (Lattice6 , SpecStory7 , Bram), to accounts generated after the code exists (as-built-architecture8 , Habitat’s Diagnostic Legibility9 , DeepWiki, Code Wiki). Cognitive Tours records what otherwise stays in developers’ heads (goals, needs, rationale and open questions), links it to the code, and is written by people for people: its skills audit and suggest, but people write the accounts for waypoints and tours. All the tools in Table I make a representation available as a deliverable intended to support understanding: a specification, context file, log, tour, or guide. They differ in what is represented, who constructs it, and whose understanding it supports. Other interventions focus on developing understanding through questioning or reflection, without making a persistent account of the software their primary deliverable (e.g., Learning 4 https://github.com/github/spec-kit 5 https://kiro.dev/ 6 https://github.com/techygarg/lattice

1 https://github.com/judell/bram

7 https://specstory.com

2 https://deepwiki.com/

8 https://github.com/gregce/as-built-architecture

3 https://codewiki.google/

9 https://github.com/Habitat-Thinking/ai-literacy-superpowers

2

Fig. 1. The Cognitive Tours interface showing a guided tour of the application itself. The waypoint graph connects user needs, design decisions, and implementation artifacts, while the commentary panel, which holds waypoint notes and docent annotations between tour stops, guides developers through the reasoning behind the system.

Opportunities10 , /grill-me11 and the Feature Comprehension Score12 ).

Waypoints are intentionally positioned on the graph by the user to help them preserve a cognitive map of the system under development that persists across time. A user composes a tour III. C OGNITIVE T OURS by selecting and ordering some of these waypoints to tell a coherent story for a particular feature or design decision. A A. Main Features: Waypoints, Relationships, and Tours tour normally traverses only some of the waypoint nodes in Cognitive Tours relies on three core concepts: a waypoint, the underlying graph. a relationship or link between two waypoints, and a tour of Tours are shared artifacts: currently a map is reached through waypoints. A waypoint is a selected anchor or landmark that a single URL with no setup, each tour records its author and the developer considers important for understanding: a system when it was last changed, and each team works in its own goal, user need, feature, architecture or design decision, AI map, so a tour one member writes becomes a path the rest of instruction, code component, test, risk, or unresolved question. the team can follow and question (see Fig. 1). Waypoints have both a description and optional commentary. Docent annotations provide human-curated commentary A waypoint can link to an existing project artifact, such as a between waypoints on a tour, explaining what matters, what specification, ADR, source file, or test. Links open the artifact to notice, and how waypoints connect. Creating these annotaon GitHub or in the developer’s IDE. tions encourages developers to articulate rationale, including Named (but intentionally untyped to be flexible) relationships decisions and alternatives that may not be recoverable from explain why nodes are connected, for example a feature the source code. addresses a user need, or a feature is implemented by a The browser interface is organized around a navigable component, or poses an architectural question or decision. waypoint graphical map and an explanatory, navigable tour view. The latter places and highlights the current stop in context 10 https://github.com/DrCatHicks/learning-opportunities 11 https://www.aihero.dev/skills-grill-me and as mentioned above, presents human-curated commentary 12 https://feature-comprehension-score.elliedocs.com/ (docent annotations). The tours may be presented and navigated

3

in the graphical view or as a markdown file (which can be member. Other tours are available for other purposes, such as exported, see Fig. 2). documenting decisions made around feature designs. Understanding why the system exists. The tour begins The tour authoring workflow allows the externalized information to evolve as the software or the team’s understanding with the motivating problem: AI-assisted development can changes. Over time some waypoints and tours may become accelerate software production faster than developers can build less relevant. Skills can recommend new waypoints and and share an understanding of what has been created. The initial waypoints establish the user needs and design goals. relationships, or updates to existing ones. Following the design rationale. The tour then connects B. AI-Supported Auditing, Human-Led Sensemaking these goals to features and design decisions. Rather than Cognitive Tours uses AI-assisted skills to help maintain navigating an unstructured collection of source files, users the waypoint graph and its curated routes. These skills audit follow an ordered sequence of waypoints accompanied by individual waypoints and entire tours, flagging material that contextual commentary (docent annotations). The underlying may need revisiting, and suggesting new waypoints or tours. A graph makes relationships between goals, features, decisions, person still decides which suggestions are meaningful, verifies and components visible. Connecting intent and implementation. The tour has the underlying evidence, writes or revises the rationale and waypoints representing intended user goals, design decisions, commentary, and determines the route through which someone implementation components and tests. The connections illuselse should encounter it. We deliberately retain the manual trate how a tour supports movement between explanations of authoring and curation work, but use AI to reduce tedious why a feature exists and the technical artifacts that realize it. discovery and maintenance work (observed blockers to our Identifying open questions or gaps in understanding. implementation from 20 years ago). Finally, the tour presents an unresolved question about the Four Claude Code skills accompany the tool: 1) auditsystem, such as whether waypoint types should be configurable. waypoints: finds waypoint descriptions that no longer match Open questions become part of the cognitive map indicating their files; 2) audit-tours: finds unrecorded recent work and where further investigation is needed. stale tour narratives; 3) suggest-waypoint: ranks recent work worth recording, then asks the author to explain it; and 4) suggest-tour: proposes where new waypoints fit, and asks the author to write each bridge between them. All four skills run in Claude Code inside the project’s repository (see the demo). They read the live map through the tool’s /api/data endpoint, the git history since a given date, and the files that waypoints link to. They never write to the map. The two audit skills report findings one at a time, such as a waypoint description that no longer matches its linked file, a tour stop narrative that names a component that has since moved, or a recently changed file that appears in no tour; the two suggest skills rank recent work worth recording and supply only the fact fields (label, type, file path, edges, stop order), followed by questions for the author. The author decides which findings to act on and writes the descriptions and narratives (a skill drafts content only on request, after first prompting the author to write their own, so that they build their own understanding).

V. E ARLY E XPERIENCE AND F UTURE W ORK

Poor understanding is not only a risk for newcomers. Cognitive debt also accrues when we move fast. In one evening of AI-assisted work preparing the tool for a fall software engineering course13 , I made more than 20 commits: a separate site and database for each of the student teams, project labels, links to each team’s GitHub repository, and nightly backups. Although I used Cognitive Tours to mitigate cognitive and intent debt through the tool development journey, during this particular coding session none of this was recorded by me in my project’s own Cognitive Tours map. The next day, I ran a skill to compare recent commits against the map to surface what may be missing and should be recorded for future sessions. To my surprise, it ranked first a design decision that contradicted an outdated ADR. Had a collaborator joined the project the next day, the map would have told them the opposite of what the code did. I deferred answering, and wrote the waypoint and a new ADR some days later. The skill I executed (to help me repay the debt I had incurred) IV. D EMONSTRATION : A T OUR OF C OGNITIVE T OURS encouraged me to walk through what was built and update We demonstrate Cognitive Tours through a tour of the appli- and add new waypoints and tours to capture this work; I cation itself, rather than an artificial example. A publicly acces- recorded the new decision as its own ADR and marked the old sible demonstration is available at https://cognitive-tours-demo. one as deferred. Figure 3 shows an excerpt. The skill ranks vercel.app/. To explore the tool, visitors can first select the decisions first, flagging any that contradict an existing ADR, “A Research Story Behind Cognitive Tours” tour from the and then asks questions rather than writing the waypoint; the application’s tour selector and navigate through its waypoints description comes from my own answers. Although recording using the Next control. The self-referential example (shown in this information was tedious, even with AI assistance, it helped the demo) serves two purposes: it introduces the design and me rebuild context and regain momentum when I returned to motivation of Cognitive Tours while illustrating how a curated development some weeks later [4]. Since this experience, I see tour can communicate the story behind a software system (see 13 see https://startup-studio.ai Fig. 1). This particular tour was created to onboard a new team

4

> /suggest-waypoint since 2026-10-20 Read the map: 59 waypoints, 73 edges, 5 tours; 28 commits since Oct 20. Worth recording, in order: 1. ADR: One site and database per team <- contradicts ADR 007 (still Accepted) 2. Feature: Team sites 3. Feature: File links that work for everyone 4. Feature: Backups for every site 5. Risk: Team sites are open > 1 - What was decided, in your words? - Why was it needed? What would confuse someone without it? - What else did you consider, and why not? > A stopgap: a site and database per team, for my course and for demos. Why: time and ease of deployment. Later: one database, team-scoped rows. Fig. 3. The /suggest-waypoint skill ranks unrecorded work and asks me about the top decision. My answer, given later and condensed here, became the waypoint’s description.

developer accounts of what matters, articulating the “why” behind decisions, reconciling intent with implementations, and preserving these accounts as the software evolves. We deliberately retain this productive friction, hypothesizing that it supports the development of human understanding rather than merely the production of documentation. This approach introduces costs and risks. Tours and links may become stale, AI suggestions may be inaccurate, and curated paths may omit important steps. Human curation can become an unnecessary burden. Whether the focus on human authorship leads to more accurate, durable, and shared understanding than AI-generated explanations remains future work. Fig. 2. A tour can be shown (and saved) as a markdown view instead of a graphical view.

R EFERENCES [1] M.-A. Storey, “From technical debt to cognitive and intent debt: Rethinking software health in the age of AI,” ACM Queue, vol. 24, no. 2, Jun. 2026. [Online]. Available: https://doi.org/10.1145/3807966 [2] T. Tavantzis, B. Trinkenreich, M. Greiler, J. C. Araújo, M. C. Araújo, I. Santos, A. Serebrenik, M.-A. Storey, and M. T. Baldassarre, “Cognitive debt in the GenAI era - listening to practitioners’ voices on the loss of understanding,” 2026. [Online]. Available: https://arxiv.org/abs/2610.37888 [3] A. Starr and M.-A. Storey, “Theory of troubleshooting: The developer’s cognitive experience of overcoming confusion,” ACM Trans. Softw. Eng. Methodol., Mar. 2026. [Online]. Available: https://doi.org/10.1145/3800945 [4] A. Starr, K. Mann, and M.-A. Storey, “Theory of developer momentum: The developer’s experience of progress and the craft of maintaining motion,” 2026. [Online]. Available: https://arxiv.org/abs/2610.24935 [5] M. Nygard, “Documenting architecture decisions,” https://cognitect.com/ blog/2011/11/15/documenting-architecture-decisions, Nov. 2011, blog post. [6] M.-A. Storey, L.-T. Cheng, R. I. Bull, and P. C. Rigby, “Shared waypoints and social tagging to support collaboration in software development,” in Proceedings of the ACM Conference on Computer Supported Cooperative Work (CSCW), 2006, pp. 195–198. [7] L.-T. Cheng, M. Desmond, and M.-A. Storey, “Presentations by programmers for programmers,” in Proceedings of the International Conference on Software Engineering (ICSE), 2007, pp. 788–792.

the value in slowing down to record the decisions and choices that may matter in the future. We plan to compare human authored, AI-generated and partially AI-generated/audited code explanations and tours to one another in terms of individual and team understanding. We will assess orientation, behavioral prediction, explanation quality, knowledge acquisition and knowledge transfer, while considering the additional effort required to create and maintain tours. We will also assess how cognitive tours can be used to foster a culture of understanding across a team, exploring how team members both curate and navigate each other’s tours and show appreciation for the effort to do so. Finally, we will assess how writing a tour and the narratives for waypoints and tour stops enhances the author’s own understanding, not only that of its readers. VI. D ISCUSSION AND L IMITATIONS The main aim behind Cognitive Tours is not to provide explanations of code. But rather it is to author deliberate

5

[8] A. Horvath, “Meta-information to support sensemaking by developers,” Ph.D. dissertation, Carnegie Mellon University, Sep. 2024. [Online]. Available: https://kilthub.cmu.edu/articles/thesis/Meta-Information_to_ Support_Sensemaking_by_Developers/26880229 [9] G. Taylor and S. Clarke, “A tour through code: Helping developers become familiar with unfamiliar code,” in Proceedings of the Psychology of Programming Interest Group (PPIG), 2022, pp. 114–126. [Online]. Available: https://ppig.org/files/2022-PPIG-33rd-taylor.pdf [10] Z. B. Kara, A. İsmail, E. Ateş, İ. N. Tamcı, Z. İyigün, S. Ş. Aslangül, Ö. Devran, B. M. Uçar, and E. Tüzün, “LACY: Simulating expert mentoring for software onboarding with code tours,” in Companion Proceedings of the ACM Symposium on the Foundations of Software Engineering (FSE), 2026, pp. 450–460. [11] J. Gao, Y. Xue, X. Xie, J. Cao, S. Thant, E. Lee, and B. Xu, “Understanding codebase like a professional! Human–AI collaboration for code comprehension,” in Proceedings of the IEEE/ACM International Conference on Program Comprehension (ICPC), 2026, pp. 343–354. [12] J. Romeo, M. Raglianti, C. Nagy, and M. Lanza, “Capturing and understanding the drift between design, implementation, and documentation,” in Proceedings of the 32nd IEEE/ACM International Conference on Program Comprehension (ICPC). ACM, 2024, pp. 382–386. [13] M. Balfroid, B. Vanderose, and X. Devroey, “Towards LLM-generated code tours for onboarding,” in Proceedings of the Third ACM/IEEE International Workshop on NL-Based Software Engineering (NLBSE). ACM, 2024, pp. 65–68.

Acknowledgement of AI Assistance. ChatGPT and Claude were used to suggest wording, improve clarity, and assist with manuscript revisions and formatting. Claude Code was used to assist with implementation of the prototype under the author’s direction, and supported the writing of some of the demo tour narratives (as notes in the waypoints).

6

Related documents

• Law Meets GenAI: Using Artificial Intelligence to Derive Conceptual Models from Legal Regulations#1178324
• GAmIfication: The Viability of Using GenAI to Create Games to Teach Legal Concepts#779982
• The Self-Improvement Problem#1357301
• Don't Prompt Your Agents. Equip Them: Skillware as a Modular Standard for Sovereign, Auditable, and Deterministic Capability Execution for Logical Systems#1571855
• EnterpriseVal: Quantifying the Efficacy, Reliability and Value of Generative AI in the Enterprise#1036230