Do the assessment on a Wednesday morning while the team makes a real change.
Pick a request that is ordinary enough to represent the system and important enough that people care when it slips. Add a field to an order, change an approval rule or update the way a customer document is classified. Follow it from request to production. If it fails, keep following it through recovery.
Technical debt appears in the waiting, duplicated work, hidden coupling and nervous manual steps around that change. A static scan can contribute evidence. It cannot show the whole bill.
Choose a change with a known finish line
Write the expected outcome before anyone opens the repository. Name the user, business event, systems affected and evidence that proves the change worked.
Avoid two bad samples. A trivial text edit will glide around the debt. A once-in-a-decade platform replacement will make every system look impossible. Choose work the team expects to perform several times a year.
Create a change trace as the work happens:
| Trace point | Evidence to capture |
|---|---|
| Request | Original need, acceptance example and decision owner |
| Discovery | Repositories, services, data, dependencies and people consulted |
| Build | Files and components changed, local setup, generated work and rework |
| Test | Useful tests, missing fixtures, unstable tests and manual checks |
| Release | Environments, approvals, scripts, waits and rollback boundary |
| Production | Logs, metrics, support signal and business read-back |
| Recovery | Detection, diagnosis, safe action, restoration and owner |
Use timestamps when they exist, but do not turn the day into surveillance. The assessment is about the system’s friction, not an engineer’s typing speed.
Separate principal from interest
The principal is the work required to remove or contain a debt item. The interest is the recurring charge while it remains.
Suppose a pricing rule is copied into four services. Consolidating it may require three weeks of engineering, migration and regression work. That is principal. Every release that needs four edits, four reviews and a reconciliation is interest. So is the risk that one copy stays stale.
Use a debt record that makes both visible:
| Debt item | Evidence from the change | Recurring charge | Consequence | Remedy range |
|---|---|---|---|---|
| Pricing rule copied across services | Four implementations changed and one differed | Repeated editing, testing and reconciliation | Inconsistent customer price | Central contract or generated shared rule |
| Production-like data unavailable | Test missed a legacy status combination | Manual staging repair and release delay | Incorrect order state | Curated masked fixture and contract case |
| Deployment owned by one person | Release paused for an unavailable operator | Queue time and knowledge bottleneck | Missed release window | Documented pipeline and supervised rehearsal |
Ranges are honest at this stage. A precise estimate before the team has tested the remedy is another form of debt.
Trace the fragile boundary
Most expensive debt is not a single ugly function. It sits where one team, data model or system depends on another.
During the observed change, mark every boundary that needed interpretation. Which service owns the field? Which schema is authoritative? Which call can be retried? Who approves the business rule? Which side detects a partial write?
For each boundary, ask for one artifact and one failure example. A useful artifact might be a schema, contract test, decision record, ownership file or runbook. A useful failure example is an incident, rejected deployment, support case or controlled injection.
No artifact does not automatically mean high debt. It means confidence must come from somewhere else and that source should be named.
Keep security debt in the same queue
Security work often lives in a separate backlog until a release or customer questionnaire makes it urgent. The assessment should connect secure-development gaps to the same system and change flow.
NIST’s Secure Software Development Framework groups practices for preparing the organization, protecting software, producing well-secured software and responding to vulnerabilities. NIST describes the practices as a common vocabulary that can be integrated into an existing development lifecycle. Use it to prompt evidence, not to manufacture a certification claim.
Check the observed path for practical gaps:
- unsupported dependencies or runtimes
- secrets or credentials without clear custody
- missing authorization tests on changed actions
- build output that cannot be reproduced
- vulnerabilities with no disposition owner
- logs that expose sensitive data or omit material actions
- a recovery step that bypasses normal controls
Put each confirmed item in the same debt record with consequence, recurring charge and owner. Do not bury a release-blocking security weakness under a general maintainability score.
Examine tests as decision tools
Test count is a poor proxy for change safety. Inspect which decision each test supports.
For the sample change, note where the team gained confidence: a focused unit test, a contract test at a service boundary, a database migration rehearsal, an end-to-end business case or a manual comparison. Then note what remained unknown.
An unstable test charges interest each time the team investigates a false failure. A missing test charges interest through manual checks or escaped defects. A slow but trustworthy suite may be cheaper than a fast suite that cannot block a bad release.
The remedy should target the actual gap. Do not prescribe a test pyramid by habit. A brittle integration boundary may need a contract fixture more than another hundred isolated unit tests.
Hold a debt hearing, not a scoring contest
Bring engineering, operations and the owner of the affected business flow together. Give each debt item five minutes.
The proposer must show:
- evidence from the observed change or operating history
- the recurring charge
- the credible consequence of leaving it
- the smallest remedy worth testing
- the measure that should move if the remedy works
The group can fund, contain, defer or reject the item. Record dissent. A debt item without evidence can return when evidence appears.
Martin Fowler’s technical debt quadrant distinguishes deliberate from inadvertent debt and prudent from reckless choices. That framing is useful because context matters. A conscious shortcut with an exit condition is different from a design whose cost was never understood.
Fund a small portfolio of remedies
Do not produce a ranked list of 200 findings. Pick a few remedies that attack different charges on the system.
One might remove a fragile boundary. Another might make a release reproducible. A third might contain a dangerous dependency until replacement is practical. Each needs a result that can be checked in normal work.
| Remedy | Outcome measure | Guardrail | Recheck point |
|---|---|---|---|
| Establish one pricing contract | One change and one reconciliation path | No new shared runtime outage boundary | Next two pricing releases |
| Create production-shaped fixtures | Legacy status cases fail before merge | No sensitive production data in fixtures | Next schema change |
| Rehearse deployment by a second operator | Release completes from documented steps | Existing approvals remain enforced | Next monthly release |
Measures can be plain: fewer repositories touched, less manual reconciliation, shorter recovery, fewer false test failures or a removed unsupported component. Do not promise a universal percentage.
Leave stable ugly code alone
Some code is unpleasant and cheap. It sits behind a stable interface, rarely changes, has known behavior and causes no meaningful operating or security exposure.
Record the decision to leave it. Name the trigger that reopens the item, such as a new product need, loss of vendor support, material incident, ownership change or unacceptable recovery result.
This is where an assessment earns trust. If every finding becomes a project, the assessor is selling renovation rather than helping the buyer allocate risk.
Accept evidence that changes the backlog
The final assessment should contain the observed change trace, confirmed debt records, rejected or deferred findings, remedy ranges, owners and recheck triggers. Include source links so another reviewer can challenge the result.
Our technical debt cost guide helps translate recurring drag into a budget conversation. This assessment has a different job. It finds where the system charges that drag and identifies the smallest remedy that can prove a change.
If the report cannot move an item into funded work, deliberate containment or an explicit decision to leave it alone, it has not assessed debt. It has described the codebase.