Visible technical debt: mapping and prioritizing with evidence
Technical debt only shows up when it explodes, in an incident or in a feature that should take days and takes weeks. AI maps that debt with checkable evidence; prioritizing what to pay off now stays your business judgment.
For months the team has repeated the same phrase in retros: "that billing module is a mess, one day it's going to blow up". Nobody points to exactly where, how much it costs to maintain, or what will break first. It's shared opinion, not a map. Then someone asks AI to sweep the entire repository and list where logic repeats, which dependencies are outdated with a known vulnerability, and which module has the worst test coverage. The report comes back with file, line, and number. The question left isn't "what's bad" anymore, it's "what on this list costs a lot right now, and what can wait".
The firm lives with the legend that "the procedural deadline management system sometimes fails", without knowing when or why. AI sweeps the tool's error records and points out that failures concentrate exactly on cases with more than one instance, because the deadline calculation logic was never updated to correctly handle appeal deadlines. The guesswork became a specific category of case with a named technical cause. Prioritizing the fix before or after another delivery from the tool's vendor stays a decision for whoever answers for the deadlines, not the sweep's.
Everyone on the people and management team comments that "the performance review system jams every cycle season", but nobody had measured the size of the problem. AI sweeps the tool's internal support tickets and points out that 40% of them concentrate on a single feature, cross-manager calibration, always in the same week of the cycle. The guesswork became a dated, localized pattern. But deciding whether it's worth investing in a fix now or waiting for the next HR vendor evaluation is a business call, not the sweep's.
The product team always knew "the app's onboarding has a weird error rate", without knowing where. AI sweeps the onboarding flow's error logs and points out that 22% of failures concentrate on a single document verification screen, tied to a third-party library that changed its response format two months ago without notice. The guesswork became a specific screen and a likely cause. Except deciding whether to fix it now or wait for the already-planned vendor migration next quarter depends on the real impact on conversion, not on the sweep itself.
The sales team complains that "the CRM is slow and freezes all the time", without knowing where to point. AI sweeps the system's performance reports and points out that a specific query, used every time someone opens a customer's history, takes twelve times longer than average, because it searches a table without a proper index since a migration two years ago. The guesswork became an exact point, with measured response time. Deciding whether this fix enters this sprint or waits depends on how much time sales loses per day because of it, a calculation that's yours, not AI's.
Operations has lived for months with the reputation that "the delivery routing system is unstable at the end of the day", without knowing the cause. AI sweeps the error logs and points out that the problem concentrates in a route recalculation function, whose complexity grew so much over the years that it now tests more than 40 different conditions in a single call, a classic sign of complexity accumulated without refactoring. The guesswork became a named function, with the number of conditions it tests. The decision to stop operations to refactor this, or push it to next quarter, is a business call.
The risk area lives with the rumor that "the data consent system has a hole", with no detail at all. AI sweeps the code and points out there's an old API route, with no documented use in the current flow, that still accepts requests without checking the data subject's consent, a remnant of an earlier version of the product. The guesswork became a specific route, with the file and the exact absence of verification. Deciding whether this is critical enough to block another delivery this week is the risk owner's judgment, not the sweep's.
The design team lives with the impression that "the app gets sluggish after some time of use", without knowing where to point. AI sweeps the main screen's code and points out that a list component loads all items at once, without pagination, since when the user base was ten times smaller, and today that tanks performance on older devices. The guesswork became a specific component with the exact cause. But deciding whether this fix enters before or after the already-planned redesign of that screen is a priority call for the team, not for the sweep that only pointed at the symptom.
The board always heard that "the market analysis platform is outdated" without any number backing that in an investment decision. AI sweeps the platform's maintenance history and points out that 60% of the reports generated last quarter needed manual correction before going to the board, rework that had never been measured. The guesswork became a number that justifies, or not, investing in a redesign before the next planning cycle. The decision to prioritize that investment, weighing the return against other bets for the quarter, stays with the board, not with AI.
Whoa, every technology team has that module everyone badmouths in the hallway and nobody can quite explain the size of the problem. "This thing is a ticking time bomb" is the phrase, and it's opinion, not diagnosis. Think with me: how much time has your team already lost arguing whether it's worth touching a debt nobody knows how to measure? Technical debt isn't a mystery, it's just invisible until you look with the right tool.
The core idea of this lesson. Technical debt stays invisible until it blows up, in an incident or in a delivery that should take days and takes weeks, because nobody tracks it systematically. AI changes this game: it sweeps the system and returns checkable evidence, file and line of duplicated logic, an old dependency's CVE number, a critical module's test coverage percentage. That trades guesswork for a map. But the map doesn't decide on its own what to pay off first. Not all debt weighs the same, and prioritizing with business judgment, looking at each item's real risk, stays yours.
01Why debt stays invisible until it explodes
Technical debt has a cruel trait: it doesn't send a warning. Nobody opens a ticket saying "today module X's technical debt went up 3%". It only shows up in two ways, and both are expensive. The first is the incident: the system breaks at a bad time and, investigating, you discover the cause was a known fragility for months, except nobody had prioritized it. The second is more subtle: a feature that should take three days takes three weeks, because the code around it is a minefield nobody wants to touch without double the care.
Remember the deadly catch that opened this module: speed without review turns into debt and incident. This is exactly where it shows up in practice. Every shortcut, every rushed fix, every quickly generated code accepted without deep review, keeps piling onto a bill nobody's watching, until it all comes due at once, at the worst possible time.
The problem isn't that debt exists, every real operation has some. The problem is it being invisible. Without visibility, the team only reacts after it's already charged the price.
02What AI does well: sweeping and pointing to evidence
Here AI is excellent, because the work is exactly the kind it covers well: sweeping through a volume of code no person would re-read in full, and pointing out concrete patterns, with references you can check. Notice the word: evidence, not opinion.
- Duplicated logic, with file and line. The same business rule written in slightly different ways in different places, each copy a risk of diverging from the others on the next fix.
- Outdated dependency, with CVE. A library stuck on an old version, with a publicly cataloged vulnerability, some with a documented severity level.
- Low test coverage, with a percentage. A critical module (the one that calculates money, the one that authenticates people, the one that processes sensitive data) running with little or no automated test protecting it.
- Accumulated complexity, with the exact point. A function that, over the years, kept gaining condition upon condition until it became a tangle harder to understand and easier to break than to fix.
What changes with this isn't just clarity. It's the possibility of deciding. With guesswork, every conversation about debt becomes an opinion debate. With evidence, the conversation becomes about priority, which is where it should be.
Learn more: why "evidence" needs to be checkable, not just detailed
A long, detailed list isn't the same thing as a list with evidence. AI can return an extensive report, full of technical adjectives, about why a module "shows signs of elevated complexity and potential excessive coupling". That sounds rigorous and can be worth nothing, if nobody can open the file and see the described problem. The right test for any item on the debt map is simple: can you point your finger at it (the file, the line, the CVE name, the exact coverage number) and have someone else confirm by looking at the same source? If the answer is yes, it's evidence. If the answer is "trust me, it said it's serious", it's still guesswork, just dressed up as a report.
03What stays the team's: prioritizing with business judgment
The map doesn't end the work, it starts the part that matters. The right question in front of any item on the list is never "what looks worst". It's another, harder one: will this specific debt cause an incident, or is it blocking a delivery that matters right now?
Think about the four findings from the start of the lesson. The tax rule duplicated across four files is ugly, but if the tax rarely changes, the risk of divergence is low, it can wait. The critical CVE in a publicly exposed image-processing library is a concrete, dated risk, it competes for immediate attention. The 8% coverage in the commission module only becomes real urgency if that module is about to be changed; if nobody's going to touch it anytime soon, the risk is smaller than it looks at first glance. The accumulated complexity in the routing function becomes a priority if it's already causing measured instability, not just because it's ugly to read.
Notice that none of these four calls came from the sweep. They came from crossing the technical finding with what the business needs in the coming weeks: what's going to change, what's exposed, what's already hurting. That's context reading, and context is yours.
04The danger of treating all debt as equal
Here lives the most common mistake once the map arrives ready: treating the list as if every item weighed the same. It's tempting to grab the easiest items to fix, a whole sprint tidying up the cheap and visible debt (renaming a variable, organizing an import, refactoring a small snippet), because it feels good, "visible progress", and fits nicely in a retro.
The problem is that, meanwhile, the expensive, hidden debt (the critical CVE, the untested module about to change next week) keeps accumulating, untouched, because it's harder, riskier to touch, and less visible day to day. A sprint of cosmetic cleanup might even improve the team's mood, and change nothing about the operation's real risk.
The right ruler isn't the size of the effort or how much the item bothers you visually. It's the business risk each item carries if nobody touches it in the coming weeks. Spending limited energy on the wrong debt is waste disguised as productivity.
05Closing: the map feeds the rest of the system
The debt map doesn't live in isolation. It's the direct antidote to the deadly catch that opened this module: it makes visible exactly what speed without review hides. Before, debt accumulated in the dark. Now, it has an address.
And it also feeds the previous lesson's choreography: when an incident shows up in backlog triage, the debt map is one more source that helps the team confirm real severity, because now there's a list of known fragilities to cross-reference against the new ticket. Guesswork becomes a map, the map becomes priority, and priority becomes fewer overnight incidents. Shall we?
Do it now
Pick a real system or module from your environment, your real task or the one everyone's already complained about informally. Ask AI to sweep it and list 3 concrete pieces of technical debt evidence, each with a reference: file and line, CVE number, or test coverage percentage.
Now do the part that's yours: for each of the 3 pieces of evidence, classify it as "expensive right now" or "can wait", and write in one sentence the business reason for the classification (what's about to change, what's exposed, what's already hurting).
If the 3 pieces of evidence came back with nothing checkable (no file, no CVE, no number), take a step back: that's still guesswork dressed up as a report, ask for the evidence again before prioritizing anything.
Practice
1. What's the difference between technical debt guesswork ('this module is a mess') and the map AI produces?
2. The sweep points to two debts: a critical CVE in a publicly exposed library, and a calculation rule duplicated in rarely changed code. What's the correct reading?
3. How does the technical debt map connect with the rest of this track's Technology module?
For the board
On guessworkthis thing is a time bomb is an opinion, not a diagnosis.
On the evidence testyou can point a finger at a source another person can open and confirm. Without that, it is still guesswork.
On prioritythe question is not what is ugliest. It is what causes an incident or blocks something that matters now.
Thanks for the feedback. It helps sharpen the next lesson.