Skip to content
EncryptTechBD
Home Industries Our Work Blog Pricing About Contact Discuss Your Project
বাংলা (BN)
Software Engineering 6 min read

Technical debt management: problems and fixes

A symptom-led diagnostic for teams whose software keeps getting slower to change, with causes, fixes, prevention and a debt register that survives the quarter.

E
EncryptTechBD · 0 comments
Laptop keyboard and code on screen
Photo: Negative Space / StockSnap

The first sign of technical debt is rarely a dramatic outage. It is an estimate nobody believes. A two-line change needs three meetings, a release waits for one person who understands the billing rules, and the upgrade that was approved last year is still on the list. The software works, but the organisation has started to route around it.

That is the useful definition for a manager: technical debt is work deferred in a way that makes future change slower, riskier or more expensive. The metaphor is financial, but the evidence is operational. You can see it in lead time, failure rate, rework and the number of people who can safely deploy.

Start from symptoms, not from code

Engineering teams often begin with a code review and a list of ugly files. Managers cannot act on that list, and it rarely connects to a business outcome. Begin instead with the friction people already describe, then trace it to a cause. The same symptom can have several causes, so treat the pairings below as hypotheses to test, not verdicts.

Seven symptoms and their usual causes

  • Every change needs a meeting. Modules share data and responsibilities, so no one can predict what a change will touch. The first fix is to draw boundaries around one business capability and expose a narrow interface, not to rearrange folders.
  • Fixes break distant features. Test coverage is thin around money, identity and order state. Add characterisation tests that capture current behaviour before changing the code, then protect the critical paths in the build pipeline.
  • Releases happen at midnight. Deployment is manual and irreversible. Build a repeatable pipeline with a staging environment, automated checks and a tested rollback before adding more features.
  • One engineer knows how a rule works. Knowledge is concentrated in a person rather than a decision record. Pair on the next change, write the rule down with its examples, and make someone else perform the deploy.
  • Estimates routinely double. Discovery is skipped and "done" is undefined. Introduce a short spike for unclear work, a definition of ready, and a review of the last five overruns to find the pattern.
  • Upgrades sit for years. Unsupported dependencies accumulate because no one owns them. Create a standing upgrade lane with a time box and a rollback plan, instead of waiting for a security incident.
  • Performance drifts each quarter. There is no budget and no measurement. Add response-time and query-count checks to the release checklist, and review the slowest transactions monthly.

Diagnose before you refactor

  1. Pick one value stream. Choose the path from customer request to delivered outcome, such as order-to-cash or enrolment-to-receipt. A debt programme without a value stream becomes a hobby.
  2. Measure the flow. Record change lead time, deployment frequency, change failure rate and recovery time for that stream. These are outcome measures, not code measures.
  3. Find the hotspots. Compare files or modules that change often with those that are complex or fragile. High change frequency plus high complexity is where interest is being paid.
  4. Interview the people who maintain it. Ask where they add workarounds, which alerts they ignore and which deploy step frightens them. Their answers are evidence, not sentiment.
  5. Write a debt register. One row per item, with the symptom it causes and the business capability it threatens. If an item cannot be connected to a symptom, park it.

The sequence matters. A refactor chosen before diagnosis usually fixes the code that is easiest to see rather than the constraint that is slowing the business.

Fixes by failure mode

Structural debt

Introduce seams around the capability that changes most. Replace direct database access between modules with an interface, document the decision, and migrate one caller at a time. A strangler approach, where new behaviour runs beside the old path until the old path can be retired, is usually safer than a simultaneous rewrite.

Test debt

Write tests that describe what the business currently depends on, especially calculations, permissions and state transitions. Contract tests protect integrations with payment, courier and accounting systems. A test suite that fails for environmental reasons trains people to ignore it, so fix flakiness before adding coverage.

Delivery debt

Make the release boring. One command should build, test and deploy the same artefact to every environment. Configuration belongs outside the code. Feature flags let a change ship dark, and a rollback path should be rehearsed rather than assumed.

Knowledge debt

Record decisions with context, alternatives and consequences. Give each critical capability a named owner and a backup. Rotate the deploy duty so the system does not depend on one person's memory.

Run a debt register that survives the quarter

Each row should carry the item, the symptom, the affected capability, the estimated interest, the effort, the risk of changing it, an owner and a decision: fix now, schedule, or accept. Review the register monthly, not weekly, and publish the accepted items so the trade-off is visible. Allocate a fixed share of delivery capacity to scheduled debt work and protect it the way you protect a customer commitment. A separate "quality sprint" that happens once a year is not a management system.

Approaches that backfire

  • Rewrite first. A rewrite discards working behaviour and rarely finishes before the business needs the next change.
  • Freeze all features. The business routes around the freeze, and the debt returns with interest.
  • Measure only code cleanliness. A tidy codebase can still be slow to deploy or impossible to operate.
  • Buy a tool and declare victory. Static analysis helps, but it does not assign ownership or create test coverage.
  • Outsource without knowledge transfer. The dependency moves; it does not disappear.

Measures that show progress

  • Change lead time from approved request to production.
  • Deployment frequency and the share of releases that need no manual step.
  • Change failure rate and mean time to restore.
  • Rework as a share of engineering effort.
  • Age of the oldest unsupported dependency.
  • Number of people who can deploy and support each critical capability.

Where custom engineering fits

We take on stabilisation and modernisation inside Custom Software & Integrations, usually starting with the value stream that hurts most. Engagement shape and commercial terms are explained on the pricing page. For the design side of maintainable interfaces, the REST API design checklist is a useful companion.

Sources

Services that deliver this

Want this implemented properly?

Pricing →

Every engagement starts with a written scope. If a requirement is outside it, we quote it separately before starting.

Responses (0)

No comments yet. Add the first one below.

Leave a response

Your email address will not be published. Required fields are marked *.

Keep reading

More field notes