Architecture and Technical Debt Triage

Technical debt is one of the most abused phrases in software. Sometimes it means real business risk. Sometimes it means code an engineer dislikes. Sometimes it means a decision that was correct at the time but has outlived its context. Sometimes it means a missing conversation between engineering and leadership.

A builder does not argue for "clean code" in general. A builder triages debt.

Five types of debt

Start by naming the debt type.

Type one: change friction. This debt makes future work slow. Examples include tangled modules, unclear boundaries, duplicated business rules, missing tests, hard-coded policies, and fragile deployment steps.

Type two: reliability risk. This debt increases the chance or impact of failure. Examples include unsafe retries, weak observability, manual recovery, poor error handling, no rollback path, and unclear ownership.

Type three: product confusion. This debt makes the product harder to use or maintain. Examples include dead features, inconsistent workflows, confusing settings, overloaded screens, and hidden states.

Type four: operational drag. This debt creates repeated manual work. Examples include support scripts, manual data corrections, custom onboarding, repeated environment setup, and human approval paths that could be automated safely.

Type five: strategic constraint. This debt blocks business moves. Examples include billing logic that prevents pricing experiments, data models that prevent enterprise reporting, permission systems that block larger customers, or architecture that prevents regional expansion.

Estimate impact, then treat it

Once the type is clear, estimate impact:

• How often does it hurt?
• Who feels it?
• What business capability does it slow or risk?
• What incidents or delays has it already caused?
• What upcoming roadmap items will be affected?
• What happens if nothing changes for six months?

Then define the treatment. Not all debt deserves immediate refactoring. Treatments include:

• Leave it and monitor.
• Add tests around it.
• Document ownership.
• Isolate the riskiest part.
• Refactor while touching related work.
• Create a strangler path.
• Remove unused capability.
• Schedule a focused debt sprint.
• Escalate as a business risk.

The strongest debt proposals connect to upcoming work. For example:

"The pricing rules are tangled. We should isolate discount logic before the enterprise pricing experiment because otherwise each experiment will require risky checkout changes."

This is stronger than: "The pricing code is bad." The first statement connects debt to a business move.

A quarterly review, not a constant one

Architecture triage should happen regularly, but not constantly. A quarterly architecture review is enough for many teams. The agenda should be practical:

• Which business capabilities are becoming harder to change?
• Which systems caused repeated incidents?
• Which modules slowed recent delivery?
• Which upcoming bets are blocked by current architecture?
• Which decisions need ADRs?
• Which debt can be paid down opportunistically?
• Which debt needs explicit investment?

Avoid architecture review theater. If no decisions come out of the review, the format is wrong.

Sequencing and ownership

For startups, the question is often sequencing. You cannot fix everything. You should fix the debt that protects the next important business move. If the company is still searching for product-market fit, heavy platform investment may be premature. If the product is scaling into enterprise customers, weak permissions and observability may become urgent.

For larger organizations, the question is often ownership. Debt survives because everyone sees it and nobody owns it. Create named ownership for critical capabilities. A capability owner does not do all the work, but they keep the map, risks, decisions, and improvement path visible.

AI can help in debt triage by summarizing code paths, finding duplication, generating tests, and drafting refactor plans. But AI may over-prioritize local code cleanliness and under-prioritize business sequencing. Use it for analysis. Keep prioritization human.

The builder rule for technical debt is this: do not ask the business to fund cleanliness. Ask it to fund speed, safety, trust, and optionality.

Key takeaways

• Name the debt type first (change friction, reliability risk, product confusion, operational drag, or strategic constraint) before proposing a fix.
• Estimate impact with concrete questions: how often it hurts, who feels it, and what happens if nothing changes for six months.
• The strongest debt proposals attach to an upcoming business move, not a general complaint that the code is bad.
• Run architecture triage quarterly, with an agenda that must produce decisions, not a recurring conversation about cleanliness.
• Use AI to analyze debt, but keep prioritization human: it tends to over-value local cleanliness over business sequencing.