A # TODO comment is a promise you make to yourself at 4pm on a Friday under deadline pressure, and promises made under deadline pressure have a way of not being kept. The comment stays, the context fades, and six months later the next person to touch that file reads # WORKAROUND: temporary fix until upstream API is updated and has no way to know whether the upstream API ever was updated, or whether this is now load-bearing code that must not be touched.
The fix is simple and takes an afternoon: a GitHub Action that flags these comments on every pull request, and a second one that opens a Jira ticket when the PR merges. The workaround itself is not the problem, and sometimes it is genuinely the right call, but “I’ll fix this later” should mean “there is a ticket for this,” not “I will remember.”
I inherited a codebase once with 340 comments matching TODO|FIXME|HACK|WORKAROUND. About half were resolved, the thing they referred to had been fixed and nobody removed the comment. A quarter were for things that had been broken for so long they were now features. The remaining quarter were real debt, some of it urgent. Without that audit nobody would have known which was which, and the audit itself took a week that should have been spent on something else.
Product managers do not read the repository. If technical debt is not in the backlog, it does not exist as far as sprint planning is concerned. Automatically converting a merged # TODO into a Jira ticket does not add work, the work was always there, it just makes it visible in the place where prioritisation actually happens.
The PR comment is the part I find most useful. A bot that flags “this PR introduces 2 workarounds” is not an accusation, it is a nudge. Sometimes you read it and spend fifteen minutes fixing the thing before it merges. Sometimes you confirm that no, this is deliberate and will be tracked. Either outcome is better than silence.
Technical debt is not the enemy. Untracked technical debt is.
If you want the implementation, the step-by-step setup is here.