TODO comments are the most insidious form of technical debt. They're visible
(you see them every time you open the file) but not actionable (there's no
ticket, no assignee, no deadline). Here's how to turn forgotten TODOs into
tracked work.
The TODO trap
You're refactoring a module. You find a section that needs a different approach
but would take another hour. You add a comment:
// TODO: refactor this to use the new auth module
You move on. The TODO stays in the code forever. Six months later, another
engineer sees the TODO, adds another TODO next to it, and now you have two
debts instead of one.
The problem: TODO comments are non-blocking. They don't fail CI. They don't
alert anyone. They're silently accumulating.
How many do you have?
Run this in your repository:
grep -r "TODO" --include=".ts" --include=".js" | wc -l
Most teams are surprised. A mid-size codebase (50k-100k lines) typically has
50-200 TODOs. Some teams have 500+. That's 500 pieces of unfinished work,
with no tracking, no assignee, and no plan.
Why this matters
TODO comments are technical debt with three worst properties:
- Visible but not actionable: Everyone sees them, no one owns them
- Don't fail tests: Unlike type errors or broken builds, TODOs don't block anything
- Compound over time: New TODOs are added faster than old ones are resolved
The result: a codebase that looks "working" but is accumulating hidden liabilities.
The automation solution
Here's how to turn TODOs into tracked work:
- Detect TODOs automatically: Run a script that scans for TODO, FIXME, HACK comments
- Parse the comment: Extract the TODO text and the file/line where it appears
- Create a ticket: Generate a Linear/Jira ticket for each TODO
- Track the debt: Include the ticket link in a code comment so it's easy to find
// TODO: refactor auth [DEBT-123]// This comment links to Linear task DEBT-123
What to track
Not all TODOs are equal. Prioritize:
- Security TODOs: Anything related to auth, encryption, data handling
- Performance TODOs: Known performance issues that could become problems
- Architecture TODOs: Code that needs restructuring before it gets worse
Low priority: minor improvements, cleanup that can wait, nice-to-haves.
The debt triage
If you have hundreds of TODOs, you can't fix them all at once. Prioritize:
- High impact: TODOs in frequently changed files
- High risk: TODOs in security-critical code
- Easy wins: Small TODOs that can be resolved quickly
Create a "technical debt" column in your backlog. Track how many TODOs you're
adding vs. resolving each week. The trend should be downward.
Preventing new TODOs
The best way to handle TODOs is to prevent them:
- Require tickets for new TODOs: If you add a TODO, create the ticket first
- Block CI on critical TODOs: Fail CI if TODO exists in security-related files
- Make TODOs visible in standup: Add "any TODOs to discuss?" to your routine
A TODO without a ticket is just a wish. A TODO with a ticket is a plan.
Deviera's
CI Intelligence
scans for TODO, FIXME, and HACK accumulation automatically — and creates a
structured ticket when the count crosses your configured threshold, so debt
doesn't stay invisible. See how it fits into the broader picture of
engineering friction measurement.