The Technical Debt That Confuses GenAI

Intro

Not all technical debt deserves the same level of urgency.

Some of it is annoying. Some of it slows teams down. Some of it is mostly harmless until the next big project comes along.

But GenAI is starting to reveal another kind of debt: the places where a system still works, but no longer explains itself very well.

That distinction matters for leaders. The goal is not to launch a grand cleanup campaign or tell developers that every old compromise was a mistake. Most technical debt exists because someone made a practical decision under real constraints.

The question is simpler: Which debt now makes it harder for people, and the AI tools helping them, to understand what the business actually means?

A Case Study

Imagine a long-running e-commerce system.

At first, the business has orders, order lines, and products. That is enough. Years later, Finance needs to report revenue by business segment.

In a clean conceptual model, that meaning probably belongs near product categories:

Order → Order Line → Product → Product Category → Revenue Segment

But the original order system does not have revenue segment. The core model is old, stable, and heavily depended on. Changing it would require testing across billing, fulfillment, reporting, forecasting, tax, and customer service.

So the team makes a practical decision.

They add revenue segment downstream in the reporting layer, close to the transaction data. The report works. The business gets what it needs. No one did anything foolish.

But the system now tells a slightly different story:

Transaction → Product
Transaction → Revenue Segment

That may be technically correct. It may also be semantically misleading.

A senior engineer who lived through the history may know what happened. They may say, “Revenue segment really belongs to product category, but we added it downstream because we could not safely change the core order model at the time.”

That human explanation matters.

Without it, an AI assistant reading the code may follow the wrong thread. It may conclude that revenue segment is fundamentally a transaction concept because that is where the mapping happens. It may miss the deeper business relationship because the true relationship lives partly in code, partly in documentation, and partly in someone’s memory.

I encountered this while testing an AI “second brain” built from years of source code, database definitions, and technical documentation. I asked where assignment information lived in the system. The assistant consistently pointed to a downstream table named Assignment because that was where much of the implementation logic appeared to converge.

From the code alone, the inference was reasonable. The table contained assignment data, many reports depended on it, and related procedures referenced it frequently. The assistant concluded that it represented the business concept of an assignment.

The history told a different story. The downstream table existed because it simplified reporting and integrated data from several operational processes. The authoritative business meaning of an assignment originated elsewhere in the operational model. The reporting table described how the organization chose to implement that concept, not where the concept itself belonged.

Once I explained the lineage and the architectural history, the recommendations changed. The implementation had been technically correct. The meaning required context that lived outside the code.

The Challenge

GenAI inherits the compromises in our code and documentation. That includes rushed fixes, deferred refactors, tactical shortcuts, downstream patches, and the “we will clean this up later” decisions that became permanent.

For years, we understood technical debt as a tax on the future. It made systems harder to modify, harder to test, and harder to reason about.

Today, technical debt can also confuse the tools we are using to understand our systems. Before dismissing those tools as useless, it is worth asking whether they are exposing places where the system can no longer explain itself from its own artifacts.

That does not make this a developer failure. It makes it a management signal.

The Lesson

This changes how we should think about cleanup.

We do not need to treat every imperfection as equally urgent. We do not need to polish every file, rename every variable, or eliminate every duplicate query before GenAI can be useful.

But we should pay closer attention to the semantic debt that appears when the business meaning of the system is no longer represented by the structure of the system.

• It shows up when the true source of meaning lives upstream, but the code applies it downstream.
• It appears when a business concept is implemented in one layer and explained in another.
• It hides where the data dictionary describes the ideal model, while the production code follows the survival model.
• It also appears when two names refer to the same concept, one name means different things in different layers, or the correct answer depends on someone remembering why a shortcut was taken years ago.

Humans often compensate with history, scars, and hallway memory. An AI assistant has to work from retrievable evidence. If the evidence is scattered, inverted, or contradicted, the answer may be plausible and wrong.

The Fix

If we want GenAI to help us understand complex systems, we need to make the important threads visible in the system itself.

Not perfect. Not pristine. Not fully modernized.

Just less dependent on tribal memory.

That is the case for right-sized refactoring.

That may mean:

• moving one important mapping closer to the concept it describes.
• adding a canonical view instead of rewriting a core model.
• documenting a downstream workaround directly beside the code that performs it.
• adding a lineage diagram that explains not only what happens, but why it happens there.
• creating a small set of golden questions that humans and AI assistants should be able to answer consistently:

Where does this concept come from?
Where is it first assigned?
Where is it transformed?
What business object owns it?
What downstream models consume it?
What known shortcuts or deferred fixes affect it?

This is not cleanup for cleanup’s sake. It is targeted investment in the places where misunderstanding is most expensive.

Leaders can make this practical by asking teams to identify a few high-value concepts where the business meaning is easy to misunderstand. Then ask the same questions before and after cleanup. Score the answers simply:

3 = Correct and explains the business relationship clearly
2 = Mostly correct, but misses lineage or ownership nuance
1 = Finds related code, but explains the business meaning incorrectly
0 = Wrong, backwards, or unsupported

The Goal

Provide our coding assistants with enough knowledge to reconstruct the intended business meaning from our artifacts.

We do not need to clean up every kind of technical debt before GenAI becomes useful. But we should prioritize debt that breaks the relationship between business meaning and implementation path.

That is the debt most likely to produce confident, plausible, backwards answers.

When a tool gives a backwards answer, it may be a model problem. It may also be a mirror. The system may have given it a coherent path to follow, but the path led away from the meaning the business actually relies on.

Right-sized refactoring is how we fix that without turning every useful compromise into a blame session.

The most dangerous technical debt in the GenAI era may be code that still runs correctly, but can no longer explain itself.