Skip to content

Draft — not approved. A working draft by UASK. It may change without notice.

Risk register and technical debt register

Status
Review
Version
0.1.4
Authority
UASK standard
Applies to
Core
Markdown source

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