Is Cognitive Debt the New Technical Debt We Should Worry About?

There's been growing conversation around the concept of cognitive debt lately—the idea that poorly structured code, unclear documentation, and confusing system architecture create a mental burden on developers that compounds over time. Unlike technical debt, which has clearer metrics, cognitive debt seems harder to measure but potentially more damaging to team productivity and mental health.

I'm curious what people's actual experiences are with this. Have you worked on projects where the sheer mental overhead of understanding the codebase became a bigger problem than the bugs themselves? Maybe you've inherited systems where the logic is technically sound but so convoluted that onboarding new team members takes months?

Some argue that cognitive debt directly impacts how fast developers can make decisions, review code, or ship features. Others think it's just another buzzword that repackages existing problems like poor documentation or over-engineering. There's also the question of whether it affects different roles differently—does a senior engineer experience cognitive debt the same way a junior one does?

How do you spot cognitive debt in your own work? And more importantly, what actually helps reduce it? Is it better architecture, clearer naming conventions, improved documentation, or something else entirely? Would love to hear what's worked (or hasn't) in your teams.