Glossary
Technical debt reporting surfaces codebase health to engineering leaders and CTOs—showing what debt exists, its impact, and recommended actions.
At Salesken, we had a 'tech debt' label in Jira with 200+ tickets. When our board asked how much technical debt we had, I couldn't give them a number. That experience taught me that unmeasured debt is invisible debt.
Technical debt reporting is communicating the state of technical debt to stakeholders. It includes: what debt exists, why it matters, what it's costing the business, and what's being done to address it.
Reporting translates technical metrics (test coverage, complexity) into business impact (velocity, reliability, hiring costs). It makes the invisible visible.
Without reporting, technical debt is invisible to leadership. Engineers know code is messy, but leadership doesn't see the impact. When leadership can't see the problem, they can't prioritize fixing it.
Reporting changes that. "Our test coverage is 30%. Industry average is 60%. We have 2x the error rate of competitors. Improving coverage would cost 3 weeks; it would save 2 weeks per quarter in fewer bugs. ROI: payback in 1.5 quarters, then ongoing savings."
Reporting also enables accountability. If you commit to improving technical debt, reporting tracks whether you delivered.
State of Technical Debt
Business Impact
Debt Paydown Plans
Progress Tracking
Executive Summary: 1 paragraph. "Technical debt is X. It's costing us Y. We're investing Z to fix it."
Key Metrics: Graphs and tables. Show trends. Compare to benchmarks.
Impact: How does debt translate to business cost? Lost velocity, bugs, support costs, hiring challenges.
Improvement Plan: What will we fix? When? Why?
Progress: How are we doing on previous commitments?
Leadership/Executives: Focus on business impact. "Technical debt is reducing shipping velocity by 15%. Addressing it would increase velocity by 10% within 6 months. Cost: 2 weeks of engineering time. Payoff: 2 weeks saved per quarter indefinitely." Connect to business outcomes.
Engineering Teams: Focus on details. "Test coverage is low in the payment module (15% vs. 60% company average). We're investing next quarter to improve it. Here's the plan." Enable them to contribute and understand priorities.
Product Managers: Focus on impact on roadmaps. "Technical debt in the auth system is slowing feature delivery. We're refactoring it next quarter, which will speed future auth-related work." Help them understand roadmap implications.
"Reporting metrics without context." "Test coverage is 30%." So what? Compared to what? Is it improving? Why?
"Too much detail." Leadership doesn't care about cyclomatic complexity. They care about: Is shipping getting slower? Are we having more bugs? Will this debt cost us money?
"Disconnecting debt from business impact." "Code complexity increased." That's technical. What's the business impact? Is it slowing shipping? Increasing bugs?
"Never reporting unless something is wrong." Report regularly: quarterly or semi-annually. Regular reporting makes debt visible even when it's stable.
"Asking for resources without a plan." "We need to refactor everything." Leadership will say no. Instead: "We're investing 2 weeks in X. Here's why. Here's the payoff." Specificity gets approval.
Instead of: "Our codebase has high technical debt."
Say: "We've identified three systems with high technical debt. Payment module: 15% test coverage (vs. 60% company average). Auth system: 3x the error rate of baseline. API layer: complexity has increased 40% in the last year. Together, these account for 15% of support tickets and 20% reduction in developer velocity. We're prioritizing payment module (highest impact, moderate effort). Timeline: 3 weeks. Expected payoff: 30% reduction in payment-related bugs, 1 week per quarter saved on future payment features."
Instead of: "We should improve code quality."
Say: "Improving code quality in our three hotspot systems would cost 6 weeks of engineering effort over the next quarter. The payoff: reduce support costs by $50k/year, reduce velocity loss by 2 weeks/quarter (worth $X), improve hiring (reduce time-to-productivity by Y). ROI: 3:1 in year one, payoff in 2 months."
Frequency: Quarterly report to leadership. Monthly report within engineering.
Format: Presentation to leadership (slides), detailed report for reference, dashboard for ongoing visibility.
Cadence: Report after you measure. Measure monthly/quarterly. Report quarterly/semi-annually.
"Good reporting makes technical debt disappear." Reporting makes it visible and enables decisions. It doesn't fix it. Action fixes it.
"We should report all technical debt." Report the important stuff. Debt that doesn't affect business impact isn't worth reporting.
"Technical teams don't want to hear about debt." Teams want to be heard. Report shows that engineering concerns are being taken seriously and acted on.
Q: How detailed should reports be?
A: Depends on audience. Executive summary: 1 page. Detailed engineering report: 5-10 pages. Don't force executives to read details they don't care about.
Q: What if debt metrics are bad?
A: Report honestly. Context matters: "Our test coverage is low, but we're early stage and shipping fast. As we mature, we'll invest in testing." Explain the context.
Q: How do we report when leadership doesn't understand technical terms?
A: Use business language, not technical. Instead of "cyclomatic complexity", say "code is hard to understand and change." Instead of "test coverage", say "code is risky to modify."
Keep reading
Related resources
