Technical Debt

Overview

Technical debt is the implied cost of rework caused by choosing a fast, easy solution now over a better approach that would take longer. Left unmanaged, it compounds: high-debt codebases ship features slower, have more incidents, and are harder to staff because engineers don't want to work in them.

Koalr's Technical Debt page turns debt from a vague complaint into a tracked, measurable metric with a cost estimate attached.

What Koalr measures

1. Rework Rate

The percentage of code that is rewritten within 21 days of being written. High rework indicates that code shipped fast was not durable — the team is paying the debt immediately.

Rework Rate = lines rewritten within 21 days / total lines written

Healthy: < 10% | Elevated: 10–25% | High debt signal: > 25%

2. Code Churn

Files and modules that are changed repeatedly. High-churn files are candidates for refactoring — they represent areas of the codebase that resist stability.

Koalr ranks the top churning files across your repos, showing:

• Change frequency (changes per month)
• Number of distinct authors touching the file
• How often changes to the file coincide with production incidents

3. Long-lived branches

Feature branches open for > 2 weeks accumulate merge debt. Koalr surfaces these alongside their age and change size.

4. PR rework cycles

PRs that are closed-without-merge and re-opened, or that undergo > 10 round-trips of comments, indicate designs that required significant rework before landing.

5. Test coverage debt

Files with no test coverage or declining coverage over time. Uncovered files in high-churn modules are a compounding risk. Integrates with Codecov and SonarCloud (see E2E Test Coverage).

Cost estimation

Koalr estimates the cost of technical debt using the following model:

Debt cost ($) = rework hours × average engineering hourly rate
Rework hours = (total lines reworked within 21 days) × 0.5h / 10 lines
Default hourly rate: $150/hr (configurable in Settings → Technical Debt)

This is a directional estimate intended for executive conversations, not accounting precision.

Dashboard sections

Organization summary

• Rework rate (current period vs. prior period)
• Estimated monthly debt cost in dollars
• High-churn file count — files changed > 5 times in the period
• Long-lived branch count — branches open > 2 weeks

Rework rate trend

12-week line chart of rework rate. A sustained decrease indicates debt paydown is working. Spikes often follow rushed feature releases.

Hot file table

Top 20 highest-churn files ranked by change frequency:

• File path and repo
• Change count in period
• Author count (how many engineers are touching it)
• Incident correlation (% of changes in this file that preceded an incident within 48h)

Team debt breakdown

Per-team rework rate and estimated debt cost. Useful for prioritizing which team's backlog needs a refactoring sprint.

Debt trend by category

Rework split by file type or directory — helps identify whether debt is concentrated in specific layers (e.g., API layer vs. database models vs. frontend).

Configuring debt tracking

Navigate to Settings → Work Configuration to set:

• Rework window — default 21 days; adjust to 14 or 30 if needed
• Engineering hourly rate — used for cost estimation
• Exclude paths — exclude generated files or vendored code from churn calculations
• High-churn threshold — number of changes in period that classifies a file as "high churn"

Paying down debt

1. Dedicated refactoring sprints — allocate 15–20% of capacity to debt reduction each quarter
2. Chore PRs — pair every feature PR with a cleanup PR in the same area of code ("leave the campsite cleaner")
3. Coverage requirements — set minimum coverage thresholds on changed files in PRs (integrates with Codecov)
4. Track progress — use the 12-week rework rate trend as your debt paydown KPI
5. Correlate with incidents — prioritize refactoring the hot files that most often precede incidents

Relationship to other metrics

• Deploy Risk — high-churn files with low coverage are core deploy risk signals (Deploy Risk)
• Code Review — high-rework PRs add to reviewer load and inflate review time
• E2E Test Coverage — coverage debt compounds rework risk (Coverage)
• ROI Dashboard — debt cost estimate feeds the engineering ROI calculation (ROI)