---
id: arch.risks-and-technical-debt
title: Risk register and technical debt register
kind: practice
domain: architecture
description: Keep two short registers in section 11 of the Blueprint - risks graded by likelihood and impact, and technical debt with its principal, interest and trigger - and review them at every release.
version: 0.1.4
status: review
authority: uask
applies_to: [core]
sources:
  - title: 'Ward Cunningham, "The WyCash Portfolio Management System" (OOPSLA 1992 experience report)'
    url: https://c2.com/doc/oopsla92.html
    license: LicenseRef-All-Rights-Reserved
    accessed: 2026-11-21
  - title: Martin Fowler, "Technical Debt" (2019)
    url: https://martinfowler.com/bliki/TechnicalDebt.html
    license: LicenseRef-All-Rights-Reserved
    accessed: 2026-11-21
  - title: NIST SP 800-30 Rev. 1, Guide for Conducting Risk Assessments (2012)
    url: https://csrc.nist.gov/pubs/sp/800/30/r1/final
    license: LicenseRef-US-Government-Public-Domain
    accessed: 2026-11-21
standards: [ISO 31000:2018, arc42 template 9.1 (October 2026)]
requires: [arch.architecture-description, arch.quality-attributes, arch.architecture-review]
related: [mgmt.governance-tiers, process.release-spec, arch.adr, arch.fitness-functions, arch.context-and-interfaces, arch.building-blocks-and-dependencies, process.knowledge-and-memory]
last_reviewed: 2026-11-21
review_every: 6
---

## Summary

Section 11 of the Blueprint holds two registers: **risks**, the things that could go wrong and what is done about them, and
**technical debt**, the shortcuts that the project took, knowingly or not, and what they cost while they stay. Both are
short tables with an owner and a date, kept in the repository and reviewed at every release. The debt register lifts the
one that the architecture review playbook (`arch.architecture-review`) writes into its report: a project can keep it all the
time and not only after a review. The grading of severity is the playbook's own and is not repeated here.

## Rules

### Risks

- **R1.** Section 11 of the Blueprint MUST hold a risk register and a technical-debt register. Each entry MUST have an id that
  is never reused: `RK-1`, `RK-2`, … for risks and `TD-1`, `TD-2`, … for debt.
- **R2.** A risk entry MUST state what could happen (a cause and an effect), what it threatens (a quality goal, a scenario,
  an interface or a date), its likelihood within the planning horizon, its impact, its severity, its mitigation, its
  response (avoid, reduce, transfer or accept), its owner, its status (open, mitigated, accepted, occurred or closed) and
  the date of its next review.
- **R3.** Severity MUST be graded from likelihood and impact by the table of `arch.architecture-review#R7`, and not from
  the effort of the fix. A project MUST state its planning horizon.
- **R4.** Accepting a risk of Medium severity or higher MUST be a decision that the owner records, which is the rule of the
  review playbook (`arch.architecture-review#R15`) carried over; the lead MAY accept a lower one and MUST log it.
- **R5.** When a Blueprint is first written, its risk register MUST have considered at least: the top quality scenarios
  (`arch.quality-attributes`), the rows of the interface inventory (`arch.context-and-interfaces`), the dependencies on
  blocks that others own (`arch.building-blocks-and-dependencies`), the end-of-support dates of the operability block, and
  the cutover and rollback when the system replaces a live one.
- **R6.** The registers MUST be reviewed with each release spec (`process.release-spec`), when the tier changes, and at
  least every three months for a live system. An entry whose review date has passed MUST be treated as stale, and a check
  SHOULD flag it.
- **R7.** When a risk occurs, its entry MUST be closed as "occurred", and the lesson MUST go where it will be found again: a
  new check (`arch.fitness-functions`), an ADR, or a new input in the list of R5 (the route and its record: `process.knowledge-and-memory#R11`). A risk that occurred twice without a new
  check MUST be raised to the owner.

### Technical debt

- **R8.** A debt entry MUST state what the shortcut is and where it sits (a block, an interface or a document), why it was
  taken (an ADR or a release spec, or "found, not chosen"), its principal (the effort to remove it, in hours or agent-days),
  its interest (what it costs while it stays: per change or per month, or a risk), the trigger when it becomes worth paying,
  its owner and the date it was entered.
- **R9.** A shortcut that is taken to meet a date or an appetite MUST be entered in the register in the pull request that
  takes it. A debt that is found MUST be entered when it is found.
- **R10.** Something with no interest is not debt: an idea or a wish MUST be kept on the roadmap, and a flaw that costs
  nothing MAY be listed as an observation.
- **R11.** When a debt's trigger has fired, the debt MUST be scheduled in a release spec, or its deferral MUST be recorded with
  a new trigger and a new date. A release spec SHOULD set aside a stated share of its appetite for debt whose trigger is near.
- **R12.** A debt that threatens a top quality scenario or that is a security or legal exposure MUST also have a risk entry,
  and the two entries MUST name each other.
- **R13.** Each exception to an architecture rule (`arch.fitness-functions#R9`) and each listed baseline violation MUST have
  a debt entry, or an ADR when it has no end date.

### Tiers

- **R14.** At the lightweight tier, both registers MAY be one table of three to ten rows that holds the known risks and every
  known shortcut, with an owner and a date for each. At the standard tier, the two registers are kept apart with all the
  fields. At the high-assurance tier, the owner MUST sign off the registers at each release, which is an owner-level
  decision (`mgmt.roles-and-decision-rights#R9`), an independent check of
  Critical and High entries applies (`mgmt.governance-tiers#R9`), and the risk register sits next to a threat model
  (`mgmt.governance-tiers#R8`).

## Guidance

### The two registers

| | Risk register | Technical-debt register |
|---|---|---|
| Question | What could go wrong, and what do we do about it? | What did we take on, and what does it cost to keep? |
| Looks | forward: something may happen | at the present: something is costing already |
| Grade | likelihood and impact give a severity | principal and interest give a pay-back |
| Closes when | the risk is gone, accepted or has occurred | the debt is repaid or written off |
| Example | the hosting provider ends support for the runtime in December | the order export reads the tables directly because there was no time for an interface |

A debt can be a risk's cause (the export that reads the tables breaks on the next schema change) and a risk can be the reason
for debt (a deadline). R12 ties the two together where it matters.

### A risk entry

| Id | Risk | Threatens | L | I | Severity | Mitigation | Response | Owner | Status | Review |
|---|---|---|---|---|---|---|---|---|---|---|
| RK-3 | The runtime loses security fixes in December, and a flaw found after that is exploited before the move to the next runtime | goal 1 (security); NFR-1 | Plausible | High | High | move to the next runtime in the March release; test on staging first | reduce | lead | open | 2027-01-15 |

L and I are the likelihood and the impact, written in the words of the grading table. Write the cause and the effect, so that
the entry says something: "the runtime loses security fixes, and the shop runs on an unsupported version", not "old runtime".

### A debt entry

| Id | Shortcut | Where | Why | Principal | Interest | Trigger | Owner | Entered |
|---|---|---|---|---|---|---|---|---|
| TD-2 | The nightly export reads the order tables directly | block B-4 | no time for an interface before the sale (release spec of 2026-10) | 2 days | each schema change needs a manual fix to the export, about 2 hours | before the stock moves to its own table, or by 2027-03-01, the end of the exception (`arch.fitness-functions#R9`) | lead | 2026-11-05 |

Principal and interest are the terms of the debt metaphor. The principal is the work of removing the shortcut. The interest is
the extra cost of everything done while it stays. Estimates are rough and the register says so; what matters is that the
owner can weigh the debt against a new feature in the same unit.

### Where entries come from

- the review of an architecture (`arch.architecture-review`), whose report has a technical-debt table and risk themes;
- a shortcut that a release spec took on purpose, to keep to the appetite;
- the end-of-support dates and the "guess, to be measured" notes of the operability block;
- the exceptions and the baseline of a fitness function;
- an incident, a failed release, or a surprise found in a pilot: each should end as a new entry or a new check.

### Paying down

Debt is repaid when a change touches it, or on a schedule. The first is cheap and it works for debt in the part of the system that
changes often. The second is for debt whose interest is paid in risk: no feature will bring it up. Put a stated share of the
appetite of each release into debt whose trigger is near (R11), and say in the release spec which entry is paid.

### Tailoring by tier

| Tier | Registers | Review |
|---|---|---|
| Lightweight | one table; the known risks and every known shortcut | at each release |
| Standard | two registers; all fields | each release spec; every three months for a live system |
| High-assurance | as standard; owner sign-off; a threat model next to the risk register | each release, with an independent check of Critical and High entries |

## Explanation

**Why two registers.** Both are about the future cost of the present state, but they are managed differently. A risk is a
possibility to weigh, mitigate or accept. A debt is a cost already being paid. Mixing them gives a list that nobody can act on:
a risk has no principal, and a debt has no probability.

**Why the debt metaphor.** Ward Cunningham's 1992 report compared shipping code that is not yet right with borrowing: a
little speeds development as long as it is repaid, and the danger is that it is not. The time then spent working around
the code is the interest. Martin Fowler's account gives the numbers a form that a project can use: the extra days a feature takes because
of the cruft are the interest, and the work of removing it is the principal. Recording both turns "the code is messy" into a figure
that an owner can weigh against a new feature, and the trigger says when the weighing comes out the other way.

**Why entries are made when the shortcut is taken.** A shortcut that nobody writes down is not a cheap loan, it is a hidden one.
Writing it in the same pull request costs a minute, and finding it later costs a review.

**Why the risk grid is not repeated.** The grading table lives in the review playbook, which developed it from the NIST practice
of combining likelihood and impact on a small qualitative scale. One place for it keeps the two documents from drifting. It is the
same table whether the risk is found by a review or entered by the project.

**Why arc42 by reference.** Section 11 of the Blueprint, "Risks and technical debt", follows arc42's order, and arc42 also groups the
two in one section. The Hub cites the structure by reference (`arch.architecture-description#R13`) and writes its own text.

## Examples

**Good.** A synthetic example: section 11 of the small UK web shop's Blueprint, at the standard tier. Planning horizon: twelve months.

Risk register:

| Id | Risk | Threatens | L | I | Severity | Mitigation | Response | Owner | Status | Review |
|---|---|---|---|---|---|---|---|---|---|---|
| RK-1 | The payment provider changes its notice format without warning, and paid orders stay "pending" | goal 2 (checkout); row I-2 | Plausible | High | High | a monitor on "no notice in 30 minutes"; the provider's change list on the monthly check | reduce | lead | open | 2027-02-01 |
| RK-2 | The courier ends version 3 of its tracking API | row I-8 | Plausible | Low | Low | read both names of the field until the end date | accept | lead | open | 2027-02-01 |
| RK-3 | The runtime loses security fixes in December, and a flaw found after that is exploited before the move | goal 1; operability block | Plausible | High | High | move to the next runtime in the March release | reduce | lead | open | 2027-01-15 |
| RK-4 | The nightly export breaks silently at the next schema change, and the accountant gets no file | row I-3; TD-2 | Plausible | Medium | Medium | the export check FF-4 fails the build; pay TD-2 | accept until TD-2 is paid | owner | accepted | 2027-01-15 |

Technical-debt register:

| Id | Shortcut | Where | Why | Principal | Interest | Trigger | Owner | Entered |
|---|---|---|---|---|---|---|---|---|
| TD-1 | The product images are not converted to a smaller format | B-1 | the sale date, release spec of 2026-10 | 1 day | pages weigh 300 KB more than they need; goal 3 is missed on 3G | before the next campaign | lead | 2026-10-20 |
| TD-2 | The nightly export reads the order tables directly (an exception to DR-1) | B-4 | no time for an interface | 2 days | about 2 hours to fix the export at each schema change | before the stock moves to its own table | lead | 2026-11-05 |

TD-2 is the exception to DR-1 that the fitness function FF-1 records (`arch.fitness-functions#R9`), and it names RK-4 as the risk
it feeds; RK-4 names TD-2 back (R12). RK-2 is Low, so the lead accepted it and logged it; RK-4 is Medium, so the owner accepted it
until TD-2 is paid (R4). The next release spec lists RK-3's move and sets aside a fifth of its appetite for TD-1 and TD-2 (R11).

**Bad.** A section 11 that says "Risks: the project may be late. Debt: some cleanup needed." There is no cause and effect, no
likelihood or impact, no owner or date, no principal or interest, and nothing to check. The first release arrives on time and
without the cleanup, and the section is not read again. Rules R2, R8 and R6 are missed.

## Sources

- [Ward Cunningham, "The WyCash Portfolio Management System"](https://c2.com/doc/oopsla92.html) — OOPSLA '92 experience
  report, 26 March 1992; all rights reserved; the origin of the debt metaphor, paraphrased, not copied. Accessed 2026-11-21.
- [Martin Fowler, "Technical Debt"](https://martinfowler.com/bliki/TechnicalDebt.html) — 21 May 2019, copyright Martin Fowler;
  the principal and the interest of the metaphor, paraphrased, not copied. Accessed 2026-11-21.
- [NIST SP 800-30 Rev. 1, Guide for Conducting Risk Assessments](https://csrc.nist.gov/pubs/sp/800/30/r1/final) — US government
  publication, public domain; risk as the likelihood of harm combined with its impact. Accessed 2026-11-21.
- ISO 31000:2018 (risk management, guidelines) — referenced by name and edition only.
- [arc42 template, edition 9.1 (October 2026)](https://docs.arc42.org/home/) — CC BY-SA 4.0; referenced for the order of
  the Blueprint's sections only; no text is adapted (`arch.architecture-description#R13`).
