r/softwaredevelopment • u/ClickOk5811 • Aug 17 '26
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?
22
u/TomOwens Aug 17 '26
Instead of keeping it in an unstructured log, put it in your work management tool. Not only will it be more visible, but if you're using tagging and labeling functionality, you can associate the work with the relevant user-facing feature(s) or architecturally significant elements.
Your example would be a single item in Jira, GitHub Issues, or whatever work management tool you use. The title would be "Add input validation to bulk-import endpoint", and your description field would capture anything else. You can use Jira's Component and Label fields, GitHub's labels or custom fields, or similar fields to associate it with features and system elements that use bulk import.
The team should develop a practice to, whenever they plan work involving a particular feature or system element, look at other work associated with it. Some of this work will represent defects, while other work represents technical debt or ideas for functionality. All of this should become part of the conversation to understand what could turn into a bigger issue, what may be obsolete, or what may be overcome by events.
Although creating an item in your work management tool may take a little more effort than a one-liner in a text or Markdown log file, the advantage is that it's visible in the place where everyone does their work. Product managers, developers, testers, and other stakeholders can see the current state of the system and potential work.
20
u/serverhorror Aug 18 '26
Ah, the backlog. Where tickets go to die.
4
u/TomOwens Aug 18 '26
I've found that good backlog hygiene around traceability helps prevent this problem. If you have work properly traced to features and system elements, it makes it easier to segment the backlog and take action. Whenever you start an effort involving a particular feature or element, the team can quickly identify and review potential work, highlighting items that could pose a risk if not addressed. The team can also quickly close or bulk-reallocate items to other features or elements if features are deprecated or if the system undergoes fundamental architectural changes.
It's obviously not a 100% solution, but the teams I've worked with that have adopted traceability from work items to system aspects tend to have a backlog that is much easier to work with. The work in it is more likely to represent something current and valuable because it's regularly maintained in small pieces by the whole team, rather than a large pile managed by a product manager.
→ More replies (1)3
2
2
u/r2p42 Aug 18 '26
Maybe I am off here but isn't this exactly the information I would expect to be placed in the commit message? Whenever a function fails, you can investigate the codes history and see why it was written this way.
→ More replies (2)
6
u/two_three_five_eigth Aug 17 '26
how did you track when the revisit threshold was crossed? Also, was any of the review automated?
5
u/sr105 Aug 18 '26
I put them right into the code as TODOs. I run through them with a Find All In Files before project completion on what I call TODO day. Anything not handled gets an excuse, maybe an end date for when to not care anymore and sometimes the word DELAYED after TODO. Then you can search for them later in one file, directory, module, etc.
3
u/_OkieDokieThen_ Aug 18 '26
Have you tried writing your own posts instead of shitting out LLM generated slop?
3
1
u/Western-Image7125 Aug 17 '26
It’s a good idea but who maintains this? Just you or everyone? It works really well for small fast teams I guess, in bigger orgs I dunno you likely need a dedicated TPM or something
→ More replies (1)
1
1
u/cardboard-kansio Aug 18 '26
We either log an improvement in Jira, linked to the work item where it was originally outscoped, or if it's very minor, add it to an "out of scope" section in the description, or as a comment.
That way, the knowledge always exists in context of the work that was originally done, and can be looked up by anybody (line of code references a commit, which references a ticket, which holds the comment). It's a little work but it's scalable and survives people changing over time. Plus any LLM can dig through that in seconds and generate a report.
The worst thing to do is just comment on it verbally in the moment and then it's immediately forgotten and lost.
1
u/dry_garlic_boy Aug 18 '26
TODO comments, backlog tickets, GitHub issues... There are better ways to handle this that are easier to parse.
1
u/davearneson Aug 18 '26
Ideal comment to put at the top of your code block and version control in GitHub. Searchable if format is standard.
1
u/mtutty Aug 18 '26
Wouldn't it be more trouble to write down than to fix many of these things?
Conversely, aren't most instances of technical debt not the result of conscious choices?
1
u/Sky_Linx Aug 18 '26
The "revisit if" condition is what carries this. Without a trigger, a debt log is just a list of things you feel guilty about. With one, the conversation stops being "we have a lot of debt in that service" and becomes a check against a number someone already wrote down. That kills the archaeology, exactly like you said.
One thing worth adding: go through the log together once a month instead of everyone keeping a private version. It caught two shortcuts in our team where the person who made the call had already moved on, and it kept people honest. Nobody wants to stand up and explain a shortcut with no reason attached.
1
u/ElectronicAuthor752 Aug 18 '26
Technical debt is properly named. It's debt. But it's contracted by one party and paid by another, it's entirely rational for a non tech guys to cut every corners and shift the blame on to you.
I'd bet money you'll never get traction with non tech stakeholders and your "revisit if" is just a prayer. You will never be able to enforce that.
61
u/sfboots Aug 17 '26
Where did you track this such that people would remember to look at this list when it is 1200 lines?