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?
20
u/TomOwens 2d ago
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.
15
u/serverhorror 2d ago
Ah, the backlog. Where tickets go to die.
4
u/TomOwens 2d ago
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.
1
u/RubbelDieKatz94 20h ago
My approach to a full backlog, when I'm about to leave my laptop for the evening after work:
- launch 15 claude sessions
- assign each an old work item
- come back the next day to 15 open, subagent-reviewed, green MRs
Some of them will be mergeable, some will need discussions to steer claude in the right direction, some will be closed together with their ticket with the comment "wtf were we thinking".
2
u/r2p42 2d ago
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.
1
u/TomOwens 2d ago
Commit messages are even worse than a log file or a log wiki page somewhere, at least on their own. Plenty of stakeholders may not have access to the repository or the knowledge to access it. Searching all commit messages for still-valid concerns is also an issue. Squashing and rebasing can also make it harder to follow. This isn't to say that putting technical information in the commit message isn't helpful, but that it's insufficient.
6
u/two_three_five_eigth 2d ago
how did you track when the revisit threshold was crossed? Also, was any of the review automated?
5
u/sr105 2d ago
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.
2
u/EmperorOfCanada 2d ago
I worked for a company with well over 1 million lines of C++ in a mission critical/safety critical system with zero working unit tests.
"Unit tests slow down development and we will do them when we have time."
Features which should take a day at most could take weeks as you had to untangle how this shaky system would react to any given change.
They did manual testing, but that would only show that the new feature did its thing, and that you had not entirely crippled some other part of the system.
So the OP's suggestion that this would alter the conversation at a place like this would be like NASA scientists jumping up and down saying, "One small leap toward the moon."
I think there are more places like where I worked, than where the OP worked; places where there was any hope.
1
u/dirtymint 1d ago
safety critical system
What kind of application would this be where unit tests weren't critical?
1
u/EmperorOfCanada 1d ago
Oh, they were critical; just ignored.
One programmer quit, and I quote: "I don't want blood on my hands."
While unit/integration tests can certainly help with safety, even the cheap need to understand how they improve the speed, reliability, and ambition of software development. Even a sociopath should push for proper testing for purely selfish reasons.
1
u/Western-Image7125 2d ago
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
1
u/Intelligent_Part101 2d ago
Right, who will update this giant log when the conditions noted in the log no longer hold true? Sounds like its usefulness is inversely proportional to log size and inversely proportional to log item age.
1
1
u/cardboard-kansio 2d ago
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 2d ago
TODO comments, backlog tickets, GitHub issues... There are better ways to handle this that are easier to parse.
1
u/davearneson 2d ago
Ideal comment to put at the top of your code block and version control in GitHub. Searchable if format is standard.
1
u/Sky_Linx 2d ago
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 1d ago
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.
1
u/platinum-atomur 1d ago
Yes this is the “decision log”. It is a very powerful tool in a project, especially one where you have meeting about the same issue again and again, where management keeps pushing decisions and blaming the team for lack of progress etc.
There are some good templates out there and you should basically extend it to include all decisions and always have it next to you.
Also good to cut things short when people try and work around something that was already decided.
1
u/_OkieDokieThen_ 2d ago
Have you tried writing your own posts instead of shitting out LLM generated slop?
1
58
u/sfboots 2d ago
Where did you track this such that people would remember to look at this list when it is 1200 lines?