Observe where changes actually become difficult
Choose a defined time window and inspect changes that were slow, repeatedly reverted or hard to review. Link each observation to a component and a concrete example. Ask maintainers which workarounds are deliberate and which are accidental.
Treat scanner findings as investigation leads. A duplicated function may be harmless, while a short permission check may carry substantial risk. Separate direct observations from assumptions that need a maintainer’s confirmation.
Describe impact and uncertainty
For every finding, state the expected harm, the people or workflows affected and the evidence supporting that judgement. Use ranges when effort is uncertain. Do not turn a guessed severity or repair duration into a measured financial amount.
A useful recommendation explains why this item should come before another. Consider frequency of change, consequences of failure and whether the affected component is about to be retired. Record the uncertainty as part of the decision.
Convert the assessment into a decision
Choose one of four outcomes: repair, investigate, accept temporarily or retire. A repair needs a bounded change and acceptance check. An accepted risk needs an owner and a revisit trigger.
The assessment is complete when the team can act on the findings, not when every file has a score. Keep enterprise-wide compliance, security certification and a full modernization programme outside a repository-focused assessment.
Working sheet
| Finding | Evidence to collect | Possible bounded outcome |
|---|---|---|
| Repeated changes to duplicated rule | Recent diffs and divergent results | Share one tested calculation |
| Unreliable release check | Failed runs and rerun history | Reproduce and repair one flaky fixture |
| Unsupported dependency | Locked version and actual usage | Upgrade with focused regression checks |
| Unowned critical module | Recent incidents and approval path | Assign owner and add boundary tests |
Questions about technical debt assessment for a repository
Is an assessment the same as measuring debt?
Measurement produces defined signals over time. An assessment interprets evidence and recommends decisions for the particular repository. Use the signals as inputs, not as automatic conclusions.
Should every finding be fixed?
No. Some compromises are rational or about to disappear with retirement work. Record the reason, owner and revisit condition when the team accepts an item.
How should I use the working sheet?
Download the CSV and replace the sample rows with evidence from your repository. Record a clear acceptance check and an owner for each item. Keep unresolved assumptions visible rather than treating the example as a completed assessment.
Sources and further reading
Examples are illustrative. They are not customer results, security guarantees, or a substitute for checking the documentation for your installed version.
