Theory of Troubleshooting: The Developer's Cognitive Experience of Overcoming Confusion

TL;DR

The paper addresses how software developers experience troubleshooting as a cognitive process and how it leads to cognitive fatigue and sustainability risk. It introduces a Theory of Troubleshooting grounded in cognitive science, built from 27 interviews using Constructivist Grounded Theory to reveal eight core theoretical categories, including the confusion experience, experiential intuition, and poking and seeing. The work foregrounds the thinking, feeling, and striving of developers over time, offering resonant language and practical implications for tool design, mentorship, and Developer Experience research. It argues that troubleshooting time can serve as a leading indicator of sustainability risk and advocates designing software and workflows that ease cognitive load while maintaining productivity and developer well-being.

Abstract

This paper introduces a Theory of Troubleshooting that is rooted in cognitive science. This theory helps software developers explain the challenges they face and the project risks that emerge as troubleshooting becomes difficult. We define troubleshooting as the cognitive problem-solving process of identifying, understanding, and constructing a mental model of the cause of an unexpected system behavior, and consider the cognitive process of troubleshooting to be an integral part of the activity of debugging. Troubleshooting is a particularly intense and draining aspect of software work, placing sustained demands on attention, working memory, and mental modeling. By surfacing and naming the confusion experience inherent in troubleshooting in terms of neurological and attentional dynamics, our theory explains how prolonged troubleshooting can deplete cognitive resources and lead to cognitive fatigue. In the study presented in this paper, we interview 27 professional developers about their troubleshooting experiences, and follow a Constructivist Grounded Theory approach to construct a theory grounded in empirical data. Our theory contributes to research on Developer Experience by providing a cognitive foundation for understanding troubleshooting difficulty, fatigue, and sustainability risk--and offers practical implications for both research and industry.

Figures (13)

• Figure 1: Redrawn debugging process model by Araki et al. showing a hypothesis-driven process araki_general_1991
• Figure 2: Overview of the data analysis process used in applying Constructivist Grounded Theory
• Figure 3: Example of the initial grounded coding from P25
• Figure 4: Example cluster of stickies from the "Troubleshooting Strategies" Miro board with the "Questioning Assumptions" focus code sticky surrounded by initial grounded code stickies with corresponding participant numbers that indicate the source of the data.
• Figure 5: Example of the sparse grounded coding process