Software Architecture / Evolution: capacity, migration, validation, and review / Lesson 17

Maintain decisions, risks, and technical debt honestly

Create concise decision records and prioritize architectural debt through observed consequences and review triggers.

About 4 min readContent reviewed 2026-10-28

On this page

Lesson goals

Record alternatives and accepted costs without rewriting decision history.
Separate uncertainty, deliberate debt, defects, and ordinary improvement work.

Explain why the choice fit its context

An architecture decision record preserves context, alternatives, a decision, and consequences. It should help a future maintainer understand why booking notifications moved to a worker, which user promise remained unchanged, and what new failure states were accepted. Keep it focused on one consequential choice rather than turning it into a project diary. A record can link diagrams and evidence without duplicating them. The important question is not whether the chosen template has every possible heading, but whether another person can assess the rationale and its limits.

Supersede a decision instead of erasing its rationale

When circumstances change, mark the earlier decision superseded and link the replacement. Preserve its original context so historical code and migrations remain understandable. A service split justified by independent teams may later be reversed after ownership consolidates; that does not make the earlier evidence disappear. Distinguish proposed, accepted, rejected, and superseded states. The sample record is deliberately compact and contains an accepted cost and review trigger. Its status is fictional documentation data, not authorization to deploy or an assertion that an actual team approved the choice.

yaml A concise architecture decision record

id: ADR-007
status: accepted in the fictional design
decision: process notifications in a separate worker
context: provider waiting must not occupy booking request resources
alternative: synchronous notification inside booking request
accepted_cost: durable delivery state and duplicate handling
review_when: workflow ownership or completion requirements change

The record links choice to a concrete concern and acknowledges cost. A real record should link supporting evidence and the responsible reviewers within the organization’s process.

Express risk as uncertainty with a consequence

The external provider might reject burst traffic is a risk only when its uncertainty, impact, and response are understood. Record the scenario, current evidence, owner, and a trigger for investigation or mitigation. Avoid inventing precise probabilities without a basis. A defect is a demonstrated failure against a requirement; a risk may never occur. A known unsupported assumption should not disappear into optimistic prose. Small evidence-gathering tasks can reduce uncertainty more effectively than a large redesign chosen before the failure mechanism is understood.

Describe the interest paid by a shortcut

Technical debt is useful language when an expedient design creates continuing future cost. A temporary shared catalog table may speed migration but require coordinated releases and duplicate validation. Record the reason, observed interest, repayment option, owner, and conditions that make repayment worthwhile. Not every disliked style is debt, and not every debt should be repaid immediately. Prioritize consequences such as repeated incidents, delayed changes, or security exposure. The illustrative register separates an observed coordination cost from an unmeasured prediction and makes the next evidence step explicit.

json A debt record with observable interest

{"item":"shared catalog write path","reason":"temporary migration overlap","observed_cost":"two policy fixes required coordinated edits","owner":"catalog boundary owner","next_step":"identify remaining direct writers","repayment_trigger":"migration parity and single-writer checks pass"}

The two fixes are fictional evidence within this example. The record avoids claiming a monetary saving or deadline without a measurement basis.

Review on meaningful change rather than ritual

Useful review triggers include a changed workload, ownership transfer, dependency retirement, repeated exceptions, or evidence that an invariant is difficult to protect. Review the relevant scenarios and decisions, not every diagram on an arbitrary schedule. End with a recorded outcome: retain, gather evidence, amend, or supersede, with an owner for remaining work. Keep unresolved risks visible without presenting them as completed fixes. This is an editorial practice lesson and executes no project management updates, approval actions, infrastructure changes, or external communications.

Common errors and fixes

An old decision is edited to pretend the new choice was always intended.

Why it happens: Historical rationale was treated as disposable.
How to fix it: Preserve the old record and link a superseding decision.
Prevent it next time: Use explicit decision lifecycle states.

Every cleanup request is called urgent debt.

Why it happens: No continuing consequence or priority evidence was described.
How to fix it: State the concrete interest and compare it with other work.
Prevent it next time: Require an owner, observed cost, and repayment rationale.

A risk register marks planned mitigation as completed.

Why it happens: Intent and verification were merged.
How to fix it: Separate planned action, implemented control, and verified evidence.
Prevent it next time: Close risks only against their stated completion criteria.

Check your understanding

1. A team dislikes the module naming convention. Is that enough to justify architectural debt repayment?

Show worked solution

No. Identify whether naming causes real navigation errors, onboarding difficulty, or repeated changes, and compare the improvement with its migration cost. It may be ordinary cleanup rather than consequential debt. Use evidence and proportionate effort instead of attaching urgency to a preference.

2. What should happen when a worker decision’s review trigger is reached?