1. LandOffer
  2. Blog
  3. All articles
  4. Make a Technical Debt Proposal That Connects Maintenance Work to Real Risk

Workplace Communication

Make a Technical Debt Proposal That Connects Maintenance Work to Real Risk

A fictional evidence memo and phased options decision connect one duplicated mapping to planned work, honest cost attribution, and a bounded maintenance investigation.

9 min readLandOffer team

A technical debt proposal should connect one design constraint to work the organization expects to do, show the evidence of extra effort or exposure, and compare a bounded repair with leaving the constraint in place. State the proposed effort, the work it would displace, and the evidence still needed before implementation. A preference for newer technology does not establish that a rewrite deserves priority.

This LandOffer.ai guide develops a fictional maintenance memo and a phased options decision. The example includes observed-looking records only as invented teaching material. No repository, incident record, customer system, or employee time record was inspected, and no maintenance change was tested or deployed.

Engineers examining one worn connector and maintenance notes beside an intact workshop assembly

Name the constraint and the change it makes harder

Start with a concrete relationship: “The export header mapping is duplicated across two paths, so each supported field change requires checking both.” That statement gives a reviewer something to investigate. “Our architecture is old” leaves the reviewer to guess which planned work is affected and why replacing it would help.

Martin Fowler's Technical Debt explanation, dated May 21, 2019, describes the additional effort internal design problems can impose on later changes. It also discusses gradual improvement and the different priorities of frequently changed and stable code. Those ideas support investigating the connection to upcoming work; they do not establish that every untidy component needs immediate replacement.

Separate related maintenance needs in the proposal. A confirmed defect needs a defect description and an appropriate response. An unsupported dependency needs its actual support dates and relevant exposure. A difficult design boundary needs evidence of change friction. These can interact, but putting all three under “technical debt” should not obscure a more urgent incident or a different decision owner.

The Software Engineering Institute's December 2016 brochure abstract connects expedient design choices with later development costs and describes making debt visible in project planning. The abstract is useful grounding; this article does not claim to have evaluated the full brochure's method or to have validated a universal prioritization formula.

Build an evidence memo before estimating a payoff

Gather enough context to distinguish recurring friction from a single difficult task. Name the affected change, the relevant design feature, the records available, and alternative explanations. Keep the original evidence accessible to authorized reviewers rather than copying private implementation or customer details into a broadly shared proposal.

Time spent during a change is not automatically time caused by debt. An unfamiliar developer, unclear requirement, missing test fixture, or delayed review can contribute. Label your attribution as an inference when you cannot separate those effects. A modest record of what happened is more useful than a precise-looking savings number built on an unobservable comparison.

Fowler's Estimated Interest, dated December 10, 2008, considers comparing actual effort with an estimate of effort in a cleaner system. He explicitly identifies the weakness of that imagined comparison. Use such estimates to frame a question for review, not to turn a hypothetical alternative into measured productivity or guaranteed cash savings.

Worked asset: the completed debt and risk memo

All people, dates, records, estimates, and decisions below are fictional. A small exhibition-planning tool exports collection lists for internal staff. Nora maintains the export code, Pavel owns product priorities, Lina reviews technical design, and Amir controls release authorization. The proposal concerns only header mapping in two CSV export paths. It does not replace the export engine, change access checks, or add a new storage service.

Nora brings memo TD-12 to the November 2 planning discussion:

Constraint: the desktop collection export and scheduled internal export each keep a separate field-to-header mapping. The original implementation optimized for a short delivery window. The paths now support the same six headers, but there is no shared mapping definition or parity check.

Upcoming exposure: two approved field-label changes are expected next quarter. A third requested field remains unapproved and is excluded from the base case. Each relevant change currently requires checking both paths. A label mismatch could cause staff to misinterpret an exported column; we have not established a financial, security, or regulatory consequence.

Evidence window: the last three completed label changes in the invented record, September 9 through October 21. Logged mapping-and-check work totals seven engineering hours. These entries are not all incremental debt cost, and the sample is too small to establish an ongoing rate.

Requested decision: authorize a two-day engineering investigation and repair-design package, with a separate implementation decision after Lina's review. Do not approve a whole export rewrite or assume a release date from this request.

Nora attaches the completed evidence table:

Fictional record What the record says What it supports and what it does not
C1, September 9 Two hours updating mappings and reviewing both outputs; both labels correct Repeated coordination across two locations; no proof a shared mapping would have saved both hours
C2, September 30 Three hours including a review correction after one path retained the old label One caught inconsistency and additional correction work; no customer incident or measured loss
C3, October 21 Two hours, including onboarding explanation for a new contributor Another two-path change; onboarding is a competing explanation for some effort
Dependency review Six shared headers in both paths; each path also contains unrelated export behavior A bounded common mapping may be possible; replacing either full path is not established as necessary

Seven hours is the sum of those three recorded entries, not a claim that seven hours can be eliminated. C2's inconsistency was caught before the fictional release review. The three change records establish neither three production failures nor the probability of a future outage. Nora preserves that limit in the memo.

She adds a separate risk statement: “If a future approved label change updates only one mapping, the exports can disagree. The existing manual comparison caught C2, but coverage and consistency of that comparison are not established. We propose investigating a shared definition and an explicit parity check.” The statement identifies a mechanism without inventing its likelihood.

Compare the minimum repair with credible alternatives

A reviewer needs to see which part of the constraint each option addresses, what remains exposed, and when the team would reconsider. Include an option that retains the current design, an option that reduces the specific constraint, and a larger alternative only if it is relevant. Do not make the preferred option attractive by hiding its testing or migration work.

Nora's completed options comparison keeps the same two approved future label changes in view:

Option Proposed work and planning allowance Remaining exposure and decision
A: retain separate mappings Keep an explicit two-path comparison in each relevant change; effort not yet estimated Duplication remains; depends on review coverage. Viable if common extraction proves too risky or planned changes disappear
B: bounded shared mapping Investigate common field definitions, specify a parity check, then estimate and review a small extraction Could reduce mapping divergence but still needs path-specific tests, integration review, and release approval. Preferred investigation direction, not proven benefit
C: replace both export paths Redesign formatting, scheduling integration, migration, and compatibility; no reviewed estimate May address wider issues, but this memo supplies no evidence that those issues justify its scope. No rewrite authorization requested

The two-day allowance covers Nora's investigation and design package, not completed extraction, migration, testing, or deployment. Lina's one-hour design review is allocated separately from Nora's two engineering days. Calling the allowance “two days to fix technical debt” would create a delivery promise the team has not made.

Pavel asks whether seven recorded hours justify two days of investigation. Nora answers that the comparison does not establish a payback. The package is proposed because two approved changes will revisit the boundary and the caught mismatch suggests a specific review weakness. If the mapping cannot be separated safely, the team may retain A rather than continue investing simply because B was preferred initially.

A small repair sketch and maintenance notebook compared with a folded whole-assembly drawing

Make the capacity and stopping conditions explicit

A maintenance proposal competes with other work even when the concern is legitimate. Name the work that will move, the people who can authorize that change, and the consequence. A cleanup can also require testing, support, or another team's time; include those dependencies before comparing its cost with feature work.

In the fictional planning discussion, Pavel can fund two engineering days next week by deferring an optional export-preview polish task. Its requester, Sima, confirms that the polish can move to the following planning review; no replacement completion date is promised. Lina accepts a one-hour design review. Amir has not authorized production work and is not asked to preapprove an unknown change.

They record this decision:

Accepted November 2: Nora will deliver the TD-12 investigation package by November 6 at 15:00 UTC. The cap is two engineering days plus Lina's separately allocated one-hour review. Pavel defers export-preview polish to the next planning review, with Sima informed and accepting that disposition.

Package contents: identify the two mapping locations and their consumers; document the six shared headers and any exceptions; propose parity-check cases; assess whether a shared definition changes path-specific behavior; provide a reviewed implementation range and unresolved dependencies.

Stop and return for decision: if extraction affects unrelated scheduling behavior, requires changing permissions, or cannot fit within the investigation cap, Nora records the finding and asks Pavel and Lina to reassess scope. She does not extend the work or start a rewrite without that decision.

Next gate: Lina reviews technical feasibility and the proposed evidence needed before implementation. Pavel then decides whether to fund B, retain A, or request a different bounded study. Any later release remains subject to Amir's normal authorization and required checks.

This is a completed proposal decision, not a completed maintenance outcome. The November 6 package, implementation estimate, review findings, and any later improvement are still future work. The useful result of the discussion is a defined investigation with capacity and limits, rather than a claim that the debt has been repaid.

Review what changes the recommendation

Add conditions under which the preferred investment becomes less attractive. If the two planned label changes are cancelled, the argument based on repeated near-term changes weakens. If investigation discovers a shared definition would couple unrelated path behavior, the small extraction may be less safe than maintaining an explicit comparison. If a confirmed active defect appears, it needs its own appropriate response rather than waiting for this planning memo.

Decide how to review a later implementation without manufacturing a before-and-after success story. The team could compare the two approved change records, whether parity checks detect deliberately introduced label mismatches in an authorized test environment, and whether path-specific behavior still meets its requirements. Those are proposed checks; no such checks were run for this article.

Keep counts and attribution honest at that later review. Fewer corrections in two changes would be a small observation, not proof that all maintenance cost has fallen. A new mapping helper can simplify one boundary while adding a dependency another team must understand. Record that cost alongside any demonstrated benefit.

For your next proposal, choose one constraint, write its evidence limits, and complete the options and capacity discussion before requesting a commitment. Save the accepted scope, capacity trade-off, named reviewer, and next decision date beside the supporting records; leave unapproved implementation and future checks visibly pending. More workplace guides are available through LandOffer.ai.

Sources and Further Reading