Tech Debt Calculator
Assess your codebase's technical debt level with our weighted severity scoring system
The Tech Debt Smell Test: Do You Have It?
Check the items that apply to your codebase. Each item is weighted by severity - some issues are more critical than others.
Code Quality
Architecture
Testing
Infrastructure & Dependencies
Documentation & Process
Performance & Operations
Your selections are saved locally and never sent to a server
Business Impact Metrics: When to Pay Down Debt
Management cares about risk, speed, and money. The most critical factors for calculating when to pay down debt are business metrics, not code metrics. Here are the top 10 factors ranked by business criticality.
Red Alert - Fix Now
Drop everything. Critical business impact.
Yellow Alert - Plan Sprints
Schedule dedicated work. Significant impact.
Green Alert - Clean As You Go
Add to backlog. Fix opportunistically.
The "Innovation Tax" Ratio
Maintenance vs. New Features
The Calculation
Measure % of engineering hours on "Keeping the Lights On" (bugs, patches, outages) vs. "New Value" (features).
The Threshold
>40-50% on maintenance = technically bankrupt. You're paying so much interest you can't touch the principal.
Action Required
Immediate freeze on new features to restore capacity.
Cycle Time Explosion
Commit to Production Time
The Calculation
Wall-clock time from "First Commit" to "Deployed to Production." Compare rolling 3-month avg vs. 12-month avg.
The Threshold
A simple change that took 2 days last year now takes 5 days (150% increase) = debt acting as friction.
Action Required
Invest in CI/CD automation and decoupling architecture.
Change Failure Rate (CFR)
Deployment Reliability
The Calculation
% of deployments resulting in a failure (rollback, hotfix, or outage).
The Threshold
>15% - If 1 in 6 releases breaks something, your team has lost trust. They'll move defensively (slowly).
Action Required
Mandatory test coverage gates and "Stop the Line" policies on broken builds.
Code Churn vs. Defect Density
The "Hotspot" Factor
The Calculation
Identify files with highest change frequency (Churn) and overlay bug tickets linked to those files.
The Threshold
Top 5 most edited files responsible for 50%+ of P1/P2 bugs = toxic hotspot.
Action Required
Isolate specific modules for immediate refactoring (Strangler Fig pattern).
Onboarding Velocity
The "New Hire" Test
The Calculation
Time for a new Senior Engineer to ship their first meaningful feature to production independently.
The Threshold
>3-4 weeks = code too coupled or undocumented ("Tribal Knowledge" debt).
Action Required
Invest in documentation and simplifying local dev environment setup.
Security & Dependency Exposure
Vulnerability Risk
The Calculation
Number of critical/high vulnerabilities in third-party packages (npm audit, Snyk, etc.).
The Threshold
Any Critical Vulnerability >30 days old. This isn't debt - it's negligence boards can be sued for.
Action Required
A dedicated "Security Sprint" to upgrade dependencies.
Technical Debt Ratio (TDR)
Fix Cost vs. Rebuild Cost
The Calculation
(Cost to fix the software) / (Cost to rebuild it). Tools like SonarQube estimate this automatically.
The Threshold
>20-30% = approaching the "Rewrite Horizon" where deleting is cheaper than fixing.
Action Required
Aggressive refactoring before hitting the "Total Rewrite" cliff.
Defect Escape Rate
Production vs. QA Bug Discovery
The Calculation
Bugs found by users in production vs. found by QA in staging.
The Threshold
If users find more bugs than your test suite, you're borrowing quality from customers.
Action Required
Shift testing left - devs must write tests, not just QA.
Documentation "Rot" Rate
Accuracy of System Knowledge
The Calculation
Manual sampling: Pick 5 random wiki pages or READMEs. How many describe the system as it actually exists?
The Threshold
<50% accuracy - if the map doesn't match the territory, devs are flying blind.
Action Required
"Docs as Code" - move documentation into the repo so it requires a PR to change.
Cyclomatic Complexity
Code Path Analysis
The Calculation
Number of independent paths through code (if/else/switch statements).
The Threshold
Functions with >15-20. Last because complex code that never changes and works is actually low risk.
Action Required
Refactor only when modifying that specific function (Boy Scout Rule).
Summary for Leadership
Red Alert (Fix Now)
#1 Innovation Tax, #2 Cycle Time, #6 Security
Yellow Alert (Plan Sprints)
#3 CFR, #4 Hotspots, #5 Onboarding, #7 TDR, #8 Defects
Green Alert (Clean As You Go)
#9 Documentation, #10 Complexity
Pro tip: If #1 or #2 are flashing red, you drop everything. If #10 is flashing, you add it to the backlog.
The "Old Version" Problem: Third-Party Library Debt
"We're on an old version of XYZ. If we're going to enhance this feature, we need to update first." Sound familiar? This is one of the most common - and most contentious - forms of technical debt.
Why This Creates Friction
The Developer's View:
- New features require newer API methods not available in old version
- Known bugs in old version force workarounds
- Documentation and Stack Overflow answers reference newer versions
- New hires know the current version, not the legacy one
Management's Concern:
- "Why does a 2-day feature now take 2 weeks?"
- "We're paying for infrastructure, not library updates"
- "What's the ROI on upgrading vs. just shipping?"
- "Last upgrade broke production for 3 days"
The Upgrade Decision Framework
Not all library debt is equal. Use this framework to prioritize:
- Known CVEs / security vulnerabilities
- Version is end-of-life (no patches)
- Blocking compliance requirements
- Breaking production intermittently
- 2+ major versions behind
- Missing features you'll need soon
- Every feature touching it adds 20%+ time
- Hard to hire devs who know old version
- Still receiving security patches
- Works fine, rarely touched
- No features blocked by old version
- Upgrade cost outweighs benefit
Calculate Your "Upgrade Tax"
Use this formula to quantify the cost of staying on old versions:
Upgrade Tax = (Extra Hours per Feature) x (Features per Quarter) x (Hourly Dev Cost)
Example Calculation:
- Extra time per feature touching React 16: 8 hours
- Features touching React per quarter: 12
- Fully loaded hourly dev cost: $150
- Quarterly Upgrade Tax: $14,400
Compare to Upgrade Cost:
- Estimated upgrade effort: 80 hours
- Upgrade cost: $12,000
- ROI: Pays for itself in <1 quarter
Common Scenarios & How to Pitch Them
"We're on Java 8 / .NET Framework 4.x / Python 2.7"
Language/Runtime EOL
Pitch: "We're running on an unsupported runtime. Any security vulnerability discovered tomorrow has no patch coming. This is a compliance and legal liability issue, not just a developer preference."
"We're 3 major versions behind on React/Angular/Vue"
Frontend Framework Lag
Pitch: "Every new hire spends 2 weeks unlearning modern patterns. Our component library is incompatible with the ecosystem. We're paying a 25% productivity tax on all frontend work."
"Our ORM/database driver is outdated"
Data Layer Debt
Pitch: "We can't use connection pooling improvements or async queries. Every database-heavy feature takes 30% longer to implement and performs worse than competitors."
"We're pinned to an old UI component library"
UI Kit Lock-in
Pitch: "New accessibility requirements (WCAG 2.1) aren't met by our old components. Either we upgrade or build custom - upgrading is 1/4 the cost of custom development."
Best Practices for Library Debt Management
Automate Dependency Tracking
Use Dependabot, Renovate, or Snyk to surface outdated packages automatically
Schedule Quarterly Reviews
Dedicate 10% of sprint capacity to "keep the lights green" maintenance
Upgrade Incrementally
Stay 1-2 minor versions behind latest, not 3 major versions
Test Coverage First
Before major upgrades, ensure 70%+ test coverage on affected areas
Track EOL Dates
Maintain a calendar of when critical dependencies lose support
Document Blockers
When old versions block features, log the business impact for ROI discussions
Tech Debt vs Tech Story: What's the Difference?
Technical Debt
The accumulated cost of past shortcuts and suboptimal decisions
It's a problem - something that slows you down right now
Developer concern - impacts code quality and velocity
Already exists - it's in production causing pain
Paying interest - ongoing cost every day
Examples:
- - Duplicated code in 10 places
- - Using deprecated libraries with CVEs
- - No automated tests
- - 2000-line god class
Technical Story
A work item to address technical needs (may or may not be debt-related)
It's a task - work to be done on the backlog
Planned work - scheduled like any other story
May be preventive - avoiding future debt
Broader scope - includes non-debt tech work
Examples:
- - Refactor payment module (debt paydown)
- - Set up monitoring (infrastructure)
- - Research new cache solution (exploration)
- - Migrate to new database (architectural)
In Practice: Technical debt is the REASON you create a technical story. The story is HOW you address it. All tech debt requires stories, but not all tech stories address debt - some are infrastructure improvements, research spikes, or preventive measures.
The Tech Debt Litmus Test
Ask these 3 questions to determine if something is technical debt:
1. Does it slow down current or future development?
If yes, it's likely debt. If no, it might just be a preference.
2. Was there a better approach available at the time (or now)?
If yes, and you chose the worse one, that's debt.
3. Would you be embarrassed to show this to a senior engineer?
If yes, and you knew better, that's reckless debt.
Want to Learn More?
Dive deeper into technical debt concepts and learn strategies to reduce it.