Tech Debt Quantification

Every engineering team knows they have tech debt. Few can quantify it. ShipLens measures technical debt per domain using signals already present in your commit history — no manual tagging, no surveys, no guesswork.

Purpose

The goal is to give CTOs a data-backed answer to the question: "Where is our tech debt, and is it getting better or worse?"

This directly supports the common engineering practice of allocating 20% of capacity to tech debt reduction. Without measurement, that 20% is either poorly targeted or quietly abandoned. With measurement, you can prove that debt-reduction work is working — or that it isn't.

Debt Signals

Tech debt is detected through three independent signals, each derived from commit data:

1. Churn Rate

How often files in a domain change over a given period.

$$\text{churn\_rate}=\frac{\text{total file modifications in domain}}{\text{total commits in period}}$$

High churn suggests instability — files that keep changing may indicate unclear requirements, poor abstractions, or accumulated shortcuts.

Churn Rate	Interpretation
< 0.1	Low — stable domain
0.1 - 0.3	Normal — active development
0.3 - 0.5	Elevated — potential debt accumulation
> 0.5	High — likely debt hotspot

2. Fix Density

The ratio of fix commits to total commits within a domain.

$$\text{fix\_density}=\frac{\text{commits of type }\mathtt{\text{fix}}}{\text{total commits in domain}}$$

A high fix density means the domain requires constant patching. This is a strong signal of underlying structural problems.

Fix Density	Interpretation
< 0.2	Healthy — mostly forward progress
0.2 - 0.4	Normal — some maintenance expected
0.4 - 0.6	Concerning — more fixing than building
> 0.6	Critical — domain is in repair mode

3. Complexity Trends

Whether the average complexity of commits in a domain is increasing over time.

$$\text{complexity\_trend}={\beta }_1\text{ (slope of linear regression on complexity over time)}$$

A positive slope means commits are getting harder over time — a classic sign that the domain's architecture is resisting change. Simple changes that should be easy are becoming difficult.

Complexity Trend (${\beta }_1$)	Interpretation
< 0	Improving — refactoring is paying off
0 - 0.02	Stable — no significant change
0.02 - 0.05	Worsening — debt is accumulating
> 0.05	Accelerating — urgent attention needed

Per-Domain Debt Score

The three signals are combined into a single debt score per domain:

$$\text{debt\_score}=\frac{\text{churn\_rate}+\text{fix\_density}+\text{normalized\_complexity\_trend}}{3}\times 100$$

Where normalized_complexity_trend maps the slope to a 0-1 range using a sigmoid function.

Debt Score	Label	Recommended Action
0 - 20	Low	No action needed
20 - 40	Moderate	Monitor; address opportunistically
40 - 60	High	Allocate dedicated debt-reduction capacity
60 - 100	Critical	Prioritize immediately; consider architectural review

Trend Tracking

Each domain's debt score is tracked over time and classified as:

Trend	Condition
Improving	Debt score decreased by > 5 points over the last 28 days
Stable	Debt score changed by < 5 points
Worsening	Debt score increased by > 5 points over the last 28 days

This lets you verify that your 20% capacity allocation is actually reducing debt in the targeted domains.

Background Processing

Tech debt scores are computed by the TechDebtWorker, an Oban background job:

Job	Schedule	What It Does
TechDebtWorker	Daily	Computes churn rate, fix density, and complexity trends per domain; calculates debt scores; classifies trends

Route

/c/:slug/tech-debt

The tech debt page shows:

• Domain-level debt scores ranked from highest to lowest
• Trend indicators (improving / stable / worsening) per domain
• Individual signal breakdowns (churn, fix density, complexity)
• Historical debt score charts per domain
• Top files by churn within each domain