About TechDebt.guru

Two jobs sit behind everything on this site, and they disagree with each other. One is the developer asking for time to fix something that is quietly costing the team a day a week. The other is the executive deciding whether that time comes out of a roadmap that has already been committed to somebody else. Both positions look obvious from the inside and unreasonable from the outside, which is most of why the conversation goes badly.

The code side started with C++ and Java, on systems that predated most of the vocabulary now used to describe them. Then monoliths, back when a monolith was simply what software was, and later the move to services - along with the discovery that distributing a tangled system mostly distributes the tangle and adds a network hop to every place it hurts. Delivery practice moved the same distance, from release trains planned quarters ahead to pipelines that ship on merge. Each of those transitions was sold as a fix for the previous one, and each of them created a fresh category of debt that nobody had a name for yet.

The leadership side ran from teams of five to organizations well past a hundred engineers, spread across North America, Europe, and Asia. Scale changes almost nothing about what debt is and almost everything about how long it takes to notice. On a small team, the person who took the shortcut is sitting next to the person who hits it. Across timezones, the shortcut and its consequence never meet - the question gets asked while the only person who knows the answer is asleep, and the team works around it instead of asking again.

The pattern that shows up in all of it: the code is not usually the problem. The code is the residue of decisions, and the decisions were usually reasonable at the time and never written down. That is why so much of this site is about conversations, records, and priorities rather than refactoring patterns. The refactoring patterns are the easy part, and they are already well documented by people who do nothing else.

Every source cited anywhere on this site lives in one shared registry file. Each entry records the publisher, the exact title, the year, an absolute link, the date the page was accessed, and a quotation actually read at that link. That last field is the one that does the work: a source nobody can quote is a source nobody read, and requiring the quote makes it impossible to cite a report from its abstract or from somebody else's summary of it.

Because the registry is shared, a correction applied once propagates to every page drawing on the same entry, instead of being patched on the one page where somebody noticed. The build refuses to complete if a citation reference points at an entry that does not exist, or if an entry is missing any of those fields. It also flags large, bold, screenshot-friendly numbers that carry no source at all, since those are the most persuasive elements on any page and were historically the least checked.

The full bibliography, what each source actually argues, and the list of sources this site deliberately refuses to cite are all on the research and citations page. That page also explains why the rules are written this specifically, which is a less flattering story than the rules themselves.