Technical Debt Is Not a Metaphor - Here's How to Put a Dollar Figure on It

Ward Cunningham introduced the technical debt metaphor in 1992, and it was useful. Talking about debt helped engineering teams communicate with business stakeholders about the cost of shortcuts. But metaphors have limits. The moment you want to make an actual decision about whether to refactor or ship the next feature, a metaphor breaks down. You need numbers.

Most teams don't have them. They know they have technical debt. They can feel it in the friction of development velocity. But when asked "how much is this really costing us?", they shrug and say something vague like "we're losing maybe 20% productivity."

That vagueness is expensive. Without a concrete dollar figure, technical debt gets deprioritized. It loses every trade-off against a feature that generates revenue next quarter. And the debt compounds silently, dragging your velocity down 3-5% per year, until suddenly you're shipping half as much as you did five years ago.

This article gives you a framework to stop guessing and start measuring. You'll learn how to inventory your technical debt, estimate the true cost in developer-hours and dollars, and make data-driven decisions about when to pay it down.

Engineering leaders hear this phrase constantly: "We're slower because of legacy code."

The problem isn't that it's untrue. The problem is that it's unmeasurable, which makes it unmovable. You can't allocate a budget to something you can't quantify. You can't prioritize it against other work. You can't even know if your refactoring effort is actually helping.

Here's what happens instead: the team makes their best guess, invests three months in a refactor, and afterward finds they shipped only slightly faster. Was the refactor worth it? Nobody knows. This frustrates engineers (who see the code is better) and confuses stakeholders (who see velocity unchanged).

The answer is to replace vague intuition with a structured approach. You need to identify debt categories, estimate remediation cost, calculate impact on velocity, and track improvements over time. That's not a metaphor anymore - it's accounting.

Technical debt isn't monolithic. Different types create different drag. Before you estimate cost, you need to categorize what you're dealing with.

1. Code Complexity Debt

Some modules have gotten so intertwined that making simple changes requires understanding five systems at once. The cyclomatic complexity is high, paths through the code are hard to follow, and logic is repeated in three places.

This debt shows up in code review friction (PRs take longer to review), in bugs (more edge cases means more failures), and in onboarding time (new engineers take longer to understand the module).

2. Duplication Debt

You've written the same validation logic five times. The authentication check exists in three different places. When you need to fix a bug in that logic, you fix it in two places and forget the third.

Duplication creates review burden (reviewers have to check if it matches other implementations) and synchronization risk (you'll eventually fix one copy and leave others broken).

3. Dependency Debt

Your production stack runs on libraries that haven't been updated in four years. The frameworks you chose are losing market share. The architecture was built for 50,000 users; you now have 500,000.

This debt compounds dangerously. Old dependencies mean security vulnerabilities, compatibility problems with new tools, and talent turnover (engineers don't want to work with deprecated tech).

4. Test Coverage Debt

Your new service has 22% test coverage. Your business logic layer is entirely untested. When you refactor that service, you have to do it by hand - no tests catch regressions.

Test coverage debt is deceptive. It costs nothing upfront (you ship faster!), but it extracts a tax every time you touch that code: manual testing, longer QA cycles, more production bugs.

5. Documentation Debt

Nobody knows why that config works. The architecture decision that led to this design pattern was made in 2019 and exists only in someone's memory. The API has no examples. The deployment runbook hasn't been updated in six months.

Documentation debt shows up as onboarding friction, as knowledge silos (the one person who understands system X becomes a bottleneck), and as mistakes when that person leaves.

6. Architectural Debt

You bolted on authentication as an afterthought. The monolith grew too large. You're using a synchronous request-response pattern that now requires caching everywhere. The data model doesn't support your current use cases, so you've added workarounds in the application layer.

This is the most expensive type of debt. It forces you into inefficient patterns throughout the codebase, slowing almost everything down.

Here's a practical process you can run through each category:

Step 1: Identify Your Debt Inventory

Go through your codebase - or ideally, ask your team to tell you where it hurts.

For code complexity: use static analysis tools (SonarQube, CodeClimate) to identify high-complexity modules. Focus on modules that change frequently and are touched by many developers.

For duplication: run a duplication detection tool. Look for copy-paste patterns, similar logic across services, repeated error handling.

For dependencies: run npm audit, pip check, or your language's dependency scanner. Identify packages that are three or more major versions behind the latest, or packages that have zero activity in the past two years.

For test coverage: run your coverage tool and identify modules below 50%. Prioritize modules that are in the critical path (authentication, payment, data models).

For documentation: look at your architecture decision records (ADRs). Count how many exist. Search your codebase for TODO comments or FIXME markers. Ask your team what's hardest to find information about.

For architectural debt: review your last few major outages. Ask "was this caused by an architectural limitation?" Review your roadmap for features that are hard to build because of structural constraints.

Step 2: Estimate Hours to Remediate Each Item

For each piece of debt, estimate the developer-hours required to fix it.

Be honest, not optimistic. If fixing a high-complexity module requires learning it, refactoring it, writing tests for it, and getting review, that might be 40 hours for a mid-level engineer. Document your assumptions.

Use these guidelines:

• Reducing complexity in a 500-line module: 15-25 hours
• Extracting a duplicated pattern (appears 3 times): 8-15 hours
• Updating a dependency (with no breaking changes): 4-8 hours
• Updating a major version: 16-40 hours (depending on API surface)
• Adding test coverage to 80% for a module: 20-35 hours
• Writing architecture decision records for an existing system: 16-24 hours per document
• Refactoring a monolith service (medium-sized): 80-120 hours
• Replacing an architectural pattern: 120-300 hours

Step 3: Calculate Impact on Velocity

Here's where you connect debt to developer speed.

For each category, estimate the velocity drag. This is the percentage reduction in development speed caused by that debt.

• High-complexity code: 8-15% velocity drag per affected module
• Duplication: 5-10% drag (slower reviews, synchronization effort)
• Outdated dependencies: 5-20% drag (compatibility problems, security reviews, limited hiring appeal)
• Low test coverage: 8-15% drag (manual testing, regression fixes, confidence issues)
• Documentation gaps: 5-12% drag (onboarding friction, knowledge silos, rework)
• Architectural constraints: 15-30% drag (inefficient patterns, constant workarounds)

Now here's the key insight: velocity drag compounds. If you have debt in three categories, it's not 8% + 5% + 10% = 23%. The effects multiply: 0.92 × 0.95 × 0.90 = 0.786, or a 21.4% drag. If you have six categories, you might be losing 40-50% of your potential velocity.

Step 4: Calculate the Dollar Cost

Use this formula:

Annual Cost of Technical Debt = (Developer Hours to Remediate × Fully-Loaded Dev Cost) + (Annual Velocity Drag × Annual Developer Payroll)

For fully-loaded developer cost, use $150-300/hour (varies by location and seniority). For annual velocity drag, calculate: (% velocity loss × 40 hours/week × 50 weeks/year × total dev team size × average developer salary).

Let's use a hypothetical Series B SaaS with 12 backend engineers.

Inventory:

• Code Complexity: Three modules with very high cyclomatic complexity (identified via SonarQube)
• Duplication: Customer validation logic appears in 5 places
• Dependencies: Three critical dependencies 2+ major versions behind
• Test Coverage: Business logic layer at 35% coverage
• Documentation: Only 4 ADRs for a 5-year-old system; most architectural decisions undocumented
• Architectural Debt: Monolithic payment system, difficult to extend for new payment methods

Hours to Fix:

• Complexity: 3 modules × 20 hours = 60 hours
• Duplication: 15 hours
• Dependencies: 3 × 25 hours = 75 hours
• Test coverage: 80 hours
• Documentation: 4 ADRs × 20 hours = 80 hours
• Architecture: 150 hours
• Total: 460 hours

Costs to Remediate: 460 hours × $200/hour = $92,000

Velocity Impact:

• Complexity: 12% drag on 3 engineers = 3.6% team drag
• Duplication: 6% drag on 2 engineers = 1% team drag
• Dependencies: 10% drag on 7 engineers = 5.8% team drag
• Test coverage: 10% drag on 4 engineers = 3.3% team drag
• Documentation: 8% drag on 10 engineers = 6.7% team drag
• Architecture: 18% drag on 7 engineers = 10.5% team drag

Combined drag: 0.964 × 0.99 × 0.942 × 0.967 × 0.933 × 0.895 = 0.737, or 26.3% velocity loss

Annual Cost of Drag:

• 12 engineers × $120k avg salary = $1.44M/year
• 26.3% drag × $1.44M = $379,000/year

Total Cost: $92,000 (remediation) + $379,000 (annual drag) = $471,000

That's the real cost of this debt. If you remediate it over the course of a year (one engineer dedicated part-time), you invest $92,000 and recover $379,000 in annual productivity. The payback period is just under three months.

Not all debt is equal. Prioritize by impact per dollar:

1. High drag, low remediation cost: Fix these first (quick wins that unlock velocity)
2. High drag, medium remediation cost: These are your priority strategic investments
3. Low drag, low remediation cost: Tackle these as an ongoing hygiene practice
4. Low drag, high remediation cost: Only fix if you're running out of higher-value work

In the example above, the dependency updates (10% team drag, $75 hours) and test coverage improvements (10% team drag, 80 hours) are quick wins. The architectural refactor (18% drag, 150 hours) is a strategic investment worth planning for.

Once you've remediated debt, measure the actual impact. Did you actually get the velocity improvement you predicted?

Compare velocity metrics before and after (use story points or commits per sprint per engineer, adjusted for project complexity). Compare bug counts. Track how long it takes to onboard new engineers.

This feedback loop matters. Your estimates might be off. The complexity you thought was worth 20 hours took 35. The dependency update unlocked 5% more velocity, not 10%. Update your estimates. Build better data over time.

Manually inventorying and estimating technical debt at scale is tedious. This is where codebase intelligence tooling helps. Platform like Glue can automatically analyze your codebase to identify complexity hotspots, duplication patterns, test coverage gaps, and dependency risks - giving you structured data instead of hunches.

The best teams combine automated analysis (which provides the inventory and spotlights the worst offenders) with human judgment (engineers who understand the impact of architectural decisions and business context).

Technical debt is real. It costs real money. Stop treating it as a metaphor and start measuring it.

Use the framework in this article to:

1. Inventory your debt across six categories
2. Estimate hours to remediate
3. Calculate velocity drag in concrete percentages
4. Put a dollar figure on the annual cost
5. Prioritize what to fix based on impact per dollar invested

With actual numbers, you can make data-driven decisions. You can argue for debt paydown not from frustration, but from a spreadsheet. You can track whether your refactoring efforts actually paid off. And you can finally build engineering roadmaps that balance feature velocity with code health.

That's not accounting - that's engineering discipline.

• SonarQube Code Analysis - Static analysis to identify complexity, duplication, and coverage gaps
• Ward Cunningham's Original Technical Debt Metaphor (1992) - The foundational concept, explained by its creator
• Accelerate: The Science of Lean Software and DevOps - Research on how code quality affects team velocity
• Architecture Decision Records (ADRs) - Standard format for documenting architectural decisions