# Review a technical debt proposal using concrete maintenance costs

Canonical: https://githtml.com/guides/review-technical-debt-proposal
Published: 2026-09-26
Publisher: WaveTech LLC / gitHtml

A technical debt review should connect a proposed change to observable maintenance friction or risk. Describe the current cost, the work it affects, and the smallest useful improvement. Compare options, including doing nothing for now, and define how the team will determine whether the change actually helped.

## Name the debt without moral judgment

An illustrative proposal might address duplicate validation rules that require several coordinated edits for one product change. That is more specific than calling the module messy. Martin Fowler's technical debt quadrant distinguishes different origins and attitudes toward debt; it is useful background, not a reason to label colleagues careless. Explain how the current design arose when evidence is available, and avoid inventing history. A deliberate earlier tradeoff can become expensive as requirements change. The review should focus on today's decision and its consequences.

## Gather a small set of real observations

Look for recent changes that touched the duplicated rules, inconsistent behavior, recurring review comments, or tests that are difficult to maintain. Use actual examples from the repository rather than imagined productivity savings. An illustrative evidence entry could link two places that encode the same rule and a change where only one was updated. If no such evidence exists, call the concern a hypothesis. Compare a local consolidation, a staged interface change, and postponement where those are credible alternatives. Include migration and review costs, not only the desired end state.

1. Problem: describe the recurring friction or risk with source evidence.
2. Options: compare a bounded improvement with broader work and postponement.
3. Verification: define the observable result that would justify the effort.

## Propose a reversible first step

A small extraction, a clarified interface, or a focused test may reveal whether the larger proposal is warranted. Do not turn every maintenance concern into a full rewrite. State what remains unchanged and which user behavior must be protected. Record the decision owner and revisit trigger if the work is deferred. A portable HTML proposal should lead with the evidence and requested decision, then place historical context afterward. Reviewers reading on a phone can assess the argument, while implementation and validation remain separate authorized work in the development environment.

## Sources and further reading

- [Martin Fowler: Technical Debt Quadrant](https://martinfowler.com/bliki/TechnicalDebtQuadrant.html)
- [Architectural Decision Records](https://adr.github.io/)

## Related guides

- [Trace data flow through a technical review document](https://githtml.com/guides/trace-data-flow-in-technical-review)
- [Review a PostgreSQL query-plan report safely](https://githtml.com/guides/review-postgresql-query-plan-report)
- [Review performance claims without being fooled by one fast run](https://githtml.com/guides/review-performance-claims-with-distributions)
- [Review test coverage by reading assertions, not percentages](https://githtml.com/guides/review-test-coverage-by-assertions)

Editorial approach: https://githtml.com/guides/about