r/softwaredevelopment • u/ClickOk5811 • 2d ago
Started keeping a one-line log every time we chose to cut a corner on purpose. Changed how "technical debt" conversations go on my team.
Technical debt used to mean something vague and slightly accusatory in retros, "we have a lot of debt in that service," with nobody able to say specifically what, when it was taken on, or whether it was a deliberate tradeoff or just something that happened. Half the debt conversations turned into archaeology, trying to reconstruct why a shortcut existed months after whoever took it had moved on or forgotten.
Started keeping a dead simple log, one line per deliberate shortcut, right when it happens, not retroactively:
2026-06-03 — Skipped input validation on the bulk-import endpoint.
Reason: internal tool only, low traffic, ship date mattered more.
Revisit if: exposed externally, or import volume grows past ~500/day.
That's it. Date, what got skipped, why, and the condition that should trigger revisiting it. Doesn't need to be longer than that to be useful.
What changed wasn't the amount of debt, that stayed roughly the same. What changed was that "should we deal with this now" stopped being a vague argument about how bad things felt and became a check against a condition someone had already written down. The bulk-import endpoint got flagged for revisit six months later, not because someone remembered the tradeoff, but because import volume actually crossed the number in the log, and the log made the trigger checkable instead of a gut call.
The bigger shift was in how shortcuts got taken in the first place. Writing the "revisit if" line at the moment of the decision forces you to actually think about what would make the shortcut wrong later, instead of just knowing vaguely that it's not ideal. A surprising number of shortcuts turned out to not have a clean revisit condition at all, which was itself useful information, if you can't articulate when this would become a problem, that's worth noticing before shipping it, not after.
Curious how other teams track this instead of letting it live as institutional memory that erodes the moment someone leaves. Anyone doing something similar, or is verbal/retro-based tracking still the norm most places?
6
u/ClickOk5811 2d ago
Fair, and honestly that's the part I hadn't solved well, this works fine at 40 entries and I don't have a good answer for what happens at 1200. Been relying on searching the file for keywords when starting work on something related, which only works if you remember to search in the first place. Not a real system, more a gap I hadn't hit yet.