Tech Debt Metrics Dashboard Guide
Last updated . Sources are named and dated inline - how we source claims.
How to build the screen: what goes on it, how it is laid out, who reads which view, how often it refreshes, and what to do when a number moves.
What This Page Covers
This page covers WHAT TO BUILD. It is about the artifact - the screen an engineering manager puts in front of their team and their director. Layout, tile anatomy, which view each audience gets, refresh and review cadence, the action to take when a tile changes, and the design mistakes that make a dashboard worse than no dashboard. It is not a metrics tutorial, and it does not define any metric: every signal named here is defined once, elsewhere.
For HOW to measure
What to instrument, where the raw data lives, collection cadence, and the full definition of the five DORA delivery metrics. See Measuring Tech Debt.
For WHICH framework
SQALE, ISO 25010, the Technical Debt Ratio, the Maintainability Index, SPACE - what each measures and where each misleads. See Measurement Frameworks.
A Dashboard Is a Communication Artifact
Most tech debt dashboards fail for the same reason: they were designed as a place to put metrics rather than as a thing somebody reads. The result is a wall of numbers that is technically complete, entirely accurate, and looked at by nobody after the second week.
The test is brutally simple. When your VP of Engineering asks "how healthy is our codebase?", you should be able to put one screen up and answer in sixty seconds, without scrolling and without apologising for anything on it. If a tile cannot survive that sixty seconds - if you would find yourself explaining why it does not mean what it appears to mean - it does not belong on the screen. Put it in the appendix, or delete it.
That constraint drives every decision on this page. A dashboard is not an archive. It has a fixed budget of attention, roughly a dozen tiles, and every tile you add spends some of the budget the others needed. The discipline of building one is mostly the discipline of leaving things off.
The rule that decides every argument: if a tile does not change a decision somebody in the room can make, it is decoration. Decoration is not neutral - it dilutes the tiles that would have changed a decision.
Three Views, Three Audiences, One Data Source
The most common structural mistake is building one dashboard for everyone. A team wallboard and a director's monthly review need the same underlying data and almost none of the same presentation. Build one pipeline, then three views over it.
The Team View
Audience: the engineers. Format: always-on wallboard or a pinned channel message.
Current state and this sprint. Delivery signals, the debt backlog counts, and anything currently breaching a threshold. Readable from across the room, which means large type and no more than six tiles.
Never put anything on here that is broken down by individual. The team view is the one that shapes daily behaviour, and it is the one where per-person numbers do the most damage.
The Manager View
Audience: you. Format: an interactive dashboard you open weekly.
Trends over quarters, broken down by module and by team. This is the only view with drill-down, because it is the only one where somebody is going to ask "which service?" and expect to find out in the same sitting.
This view carries the ugly detail: the module nobody wants to own, the backlog item that has been open for two years, the flat line where an initiative was supposed to show up.
The Director View
Audience: leadership. Format: one static page, monthly or quarterly.
Four tiles at most, every label written in business language, every number paired with the direction it moved and one sentence saying why. No engineering vocabulary survives to this view.
This view is a snapshot, not a live link. Leadership looking at a live dashboard between reviews generates questions about noise, and you will spend the following week explaining variance.
Anatomy of the Screen
Lay the manager view out in four horizontal bands, top to bottom, in the order a question actually gets asked: how are we, which way are we going, where is the problem, and what are we doing about it.
Band one: the headline row
Four tiles, no more, across the top. This is what somebody sees before they decide whether to keep reading. Pick tiles that move slowly enough to be meaningful and fast enough to be current - typically an overall grade, the debt ratio, one delivery signal, and one stability signal. Everything here must be readable at a glance from a doorway.
Band two: the trend band
One wide chart with at least twelve months on the x-axis. Direction matters more than level, and a twelve-month window is the shortest one that cannot be cherry-picked. Annotate it: mark the sprint you started the remediation initiative, the month you onboarded four people, the release that went badly. An unannotated trend line invites everyone to supply their own explanation, and they will each supply a different one.
Band three: the breakdown
The same headline numbers, split by module, service, team, or repository. This band exists because aggregates hide the thing you need to act on: a comfortable organization-wide average routinely contains one service that is on fire. Sort it worst-first and resist the urge to make it alphabetical.
Band four: the action list
The band almost every dashboard omits, and the one that decides whether anybody comes back next week. Three to five current commitments, each with an owner and a date, each traceable to a tile above it. Without this band a dashboard is a weather report. With it, it is a plan with evidence attached.
Anatomy of a Single Tile
Every tile carries five things. Drop any one of them and somebody will misread the tile within a month.
1. The number, and its unit
Large, and unambiguous about what it counts. "12%" is not a tile; "change failure rate, 12% of deploys" is.
2. The direction, versus a stated period
An arrow and a delta against a named baseline - last quarter, not "before". Colour the arrow by whether the movement is good, which is not always up.
3. A sparkline
Enough history to show whether this move is unusual. A single delta cannot distinguish a real change from ordinary week-to-week noise, and most tiles are noisier than they look.
4. An owner
A named person or team who explains this tile when it moves. Unowned tiles rot: the definition drifts, the feed breaks, and nobody notices for two quarters.
5. A written response, decided in advance
One sentence saying what happens when this tile moves the wrong way. Deciding the response in advance, in calm conditions, is the entire difference between a dashboard that drives action and a dashboard that drives meetings about the dashboard. If you cannot write that sentence, you have found a tile that should not exist.
Example Layout: The Manager View
The four bands, assembled. This is a layout, not a benchmark. The headline tiles are deliberately left as placeholders rather than plausible-looking numbers, because a screenshot of a wireframe is exactly how an invented figure starts circulating as a target. Everything below the headline row is illustrative filler; nothing here is a number to aim at.
An illustrative layout for a codebase partway through a remediation programme. Yours will start redder, and that is the point of keeping the twelve-month band.
Choosing the Right Panel Type
Most dashboard panels should be a number with a sparkline. Reach for a full chart only when the point you are making is a shape rather than a value. The two shapes worth a panel are a trend over time, and a relationship between two things people believe are unrelated.
Example: A Relationship Panel
A panel earns its space when it settles an argument. This one puts unplanned debt work next to how the team says it feels, on one axis, so the two stop being discussed separately.
| Team, by share of unplanned debt work | Satisfaction score (1-5) |
|---|---|
| Team A, 5 percent debt | 4.6 |
| Team B, 15 percent debt | 4.1 |
| Team C, 25 percent debt | 3.4 |
| Team D, 40 percent debt | 2.5 |
| Team E, 60 percent debt | 1.8 |
Illustrative shape only - not measured data.
Illustrative shape only - not measured data. Build this panel from your own survey and sprint records.
The AI-Assisted Code Band
If a meaningful share of your production code arrives with AI assistance, the dashboard needs a band for it - because without one, AI-generated debt accumulates inside your existing tiles and is indistinguishable from the human-created kind until something breaks. Add these as a separate band on the manager view only; they are too new and too noisy for a wallboard.
AI-Assisted Change Share
The share of merged changes that were primarily AI-generated. On its own this is a context tile, not a health tile - it exists so the other three can be read properly.
When it moves: nothing, by itself. Check whether review capacity moved with it.
Defect Density Gap
Defect density in AI-assisted changes minus defect density in human-only changes. A gap tile rather than two separate tiles, because the comparison is the whole point.
When it moves: a widening gap is a review-process problem before it is a tooling problem.
Post-Merge Revert Rate
How often AI-assisted changes are reverted after merge. High revert rates mean code is passing review and failing in production, which is a statement about the review, not the model.
When it moves: sample five reverts and read the review threads. The pattern will be obvious within an hour.
Nonexistent Dependency Count
Packages or API calls introduced that do not exist upstream, or are deprecated. This is the one AI tile with an absolute target rather than a trend.
When it moves: above zero is an incident. Treat it as one.
Deep dive: For a complete framework on managing AI-generated code quality at scale, see our Managing AI Code Quality guide.
Refresh Cadence and Who Reads It
Refresh rate and review rate are two different settings, and the common mistake is matching them. Refresh the data as fast as it arrives; review it at the rate a decision can actually be made. A dashboard reviewed daily generates reactions to noise, and reactions to noise are how a measurement programme loses its credibility.
Every Sprint
Team view, in the retrospective
- Anything currently breaching
- What was closed, and celebrate it
- Whether the action list moved
- Any tile nobody understood
Monthly
Manager view, with peers
- Trend direction on each band
- Module breakdown, worst first
- Rebalance the next sprint's allocation
- Retire tiles nobody used
Quarterly
Director view, as a snapshot
- Four tiles, business language
- What the last quarter's work bought
- Risks that need a decision
- The ask, with a number attached
Annually
The dashboard itself, under review
- Which tiles changed a decision?
- Which feeds silently broke?
- Which definitions drifted?
- Delete at least one tile
Alerting: What Interrupts Somebody
Almost nothing on a tech debt dashboard deserves a notification. Alerts are for conditions that are unambiguous, actionable immediately, and rare enough that people still read them after six months. Everything else waits for the review.
Never alert
- Coverage moving by a point
- Complexity averages
- Any single-sprint change
- Anything with a seasonal pattern
Flag in the review
- A tile outside its own historical range
- Three consecutive periods in one direction
- Unplanned work share rising twice running
- Any tile whose feed has gone stale
Interrupt somebody
- Critical debt count above zero
- A newly published security advisory in a dependency
- A runtime passing end of life
- A nonexistent dependency reaching main
Note what is missing from the right-hand column: every threshold there is a state, not a comparison against an industry number. That is deliberate. Alerting on "we fell below the benchmark" requires a benchmark you can defend, and for delivery metrics no such published benchmark currently exists.
What to Do When a Number Moves
Write this table before you need it, and put a link to it on the dashboard itself. The first question is always the same one - is this real? - because the most common cause of a tile moving is that something about the measurement changed, not something about the code.
| The tile moved | First question | Then do this |
|---|---|---|
| Any tile, sharply, in one period | Did the measurement change? A rule set, a repository added, a definition edited? | Check the change log for the pipeline before you check the code. Most step changes are measurement changes. |
| Deployment frequency falling | Is it fewer releases, or the same releases batched larger? | Read it next to lead time. Both worsening is a pipeline or confidence problem; only frequency worsening is usually a planning change. |
| Change failure rate rising | Is it concentrated in one module? | Go to the breakdown band first. A concentrated rise is a remediation target; a spread rise is a process gap in review or testing. |
| Unplanned work share rising | Is planned debt allocation being consumed by it? | This is the clearest signal that interest is outrunning payments. It is the number to take into the next planning conversation. |
| Debt items created dropping | Is the codebase improving, or has logging stopped? | Check escaped defect share in the same window. If that is rising while creation falls, people have stopped writing things down. |
| Coverage rising, defects flat | Did test quality rise, or just test quantity? | Treat a coverage rise with no downstream effect as a warning, not a win. Sample the new tests. |
| Everything improved at once | Did the team shrink, the scope narrow, or a repository leave the sample? | Be as suspicious of good news as bad. A dashboard that only gets challenged when it is red will eventually only be red when it cannot be avoided. |
When to Escalate, and to Whom
Escalation triggers should be relative to your own history or absolute states of the world - never a borrowed industry threshold, because you will be asked where the threshold came from and there is frequently no defensible answer.
Raise with your manager
- Debt ratio worse than your own baseline for two quarters
- Unplanned work share above the planned allocation
- Delivery throughput declining across three sprints
Escalate to the director
- Stability signals degrading while throughput is flat
- Confidence survey falling in a revenue-critical module
- A remediation initiative with no measurable effect after a quarter
Executive attention
- Unpatched security exposure in debt-heavy code
- A dependency or runtime past end of life
- Attrition citing code quality in exit interviews
Dashboard Anti-Patterns
These are design faults in the artifact, not faults in the underlying metrics. Every one of them has shipped on a dashboard built by somebody competent, because each seems reasonable at the moment it is added.
The vanity tile
Lines of code, commit counts, tickets closed. Numbers that always go up, look like productivity, and reward exactly the behaviour you are trying to reduce. They survive on dashboards because they are easy to collect and nobody can argue they are wrong.
Fix: for every tile ask what a person could do to improve it dishonestly. If the answer is easy, remove the tile.
The tile that became a target
The moment a number appears in a performance conversation or an objective, it stops describing the system and starts describing the incentive. Coverage climbs, assertions vanish, and the tile looks better every month while nothing improves.
Fix: state in writing that dashboard tiles are never inputs to individual evaluation, and pair every tile with a companion that would move the other way if it were gamed.
The per-person breakdown
Publishing per-developer commit counts, PR throughput, or review statistics turns engineering into a scoreboard. The engineer who spent the week unblocking three teammates renders as the least productive person on the screen, and everyone learns the lesson within a sprint.
Fix: the smallest unit on any view is a team. There is no version of this tile that is safe.
Permanent red
A tile that has been red since the dashboard was built is no longer information; it is wallpaper. Worse, it teaches everyone that red is a normal colour, which is precisely the belief you need absent on the day something is genuinely wrong.
Fix: any tile red for two consecutive quarters gets either an owner and a date, or a rebaselined threshold. Not a third quarter of red.
The silently stale feed
A credential expires, a job stops running, and a tile keeps displaying its last value looking exactly as authoritative as it did the day before. This is the most dangerous failure on the page because it produces confident decisions from stale data.
Fix: every tile shows its own last-updated timestamp, and grays itself out past its expected refresh interval.
The borrowed benchmark
A threshold line labelled "industry standard" that nobody on the team can trace to a source. It survives because it is never questioned until the one meeting where it is, and then the whole dashboard's credibility goes with it.
Fix: every threshold on the screen is either your own baseline or carries a citation you have personally read. There is no third category.
Frequently Asked Questions
One screen, six tiles, one twelve-month trend chart, and an action list. Four of the tiles come from your delivery pipeline and incident tracker, and two from the debt labels in your backlog. Everything else is version two. Build it as a static page refreshed by a scheduled job before you build it as an interactive tool, because the constraint of a fixed layout forces the editing decisions that make it readable. If it takes more than a sprint to stand up, you have chosen tiles whose data you do not actually have yet - a data problem, not a dashboard problem.
Trends by default, targets only where you can defend the number. A target line is a promise that somebody chose that value for a reason, and if the reason is "it was in an article" the tile is worse than having no line at all. Safe targets are absolute states you control - critical debt count at zero, no runtime past end of life - and relative goals derived from your own history, such as "median lead time below last quarter's". Avoid target lines on delivery metrics that imply an industry grade; the numeric performance-cluster thresholds widely attributed to DORA are not supported by its current publications, which is exactly the kind of line that collapses under one question in a review.
Yes, with one hard caveat: only team-level views are public. Put the team view on a screen in the team area or pin it in a channel, and review it in retrospectives. Shared visibility is what turns a metric from something management tracks into something the team owns - when the trend improves it creates shared pride, and when a tile goes red it creates shared ownership of the fix rather than a search for whose commit did it. Never publish anything broken down by individual, on any view. That single decision determines whether the dashboard is read as a tool or as surveillance, and once it is read as surveillance you will not get that back.
Ready to Build Your Dashboard?
Six tiles, one trend chart, an action list, and a named owner for each. Everything else is version two.