Assumptions
What Is an Assumption in ArchRepo?
An Assumption is a statement that is believed to be true for the project or solution, but has not yet been confirmed. It represents a gap in knowledge — something the team is treating as fact in order to proceed, while acknowledging that it may need to be revisited.
Assumptions are distinct from related concepts in the RAID framework:
| Concept | What it represents |
|---|---|
| Assumption | Something believed to be true but not yet confirmed |
| Risk | A potential future problem — something that might go wrong |
| Issue | A problem that is already happening and needs resolution |
An assumption that turns out to be wrong typically escalates into a risk or an issue. Tracking assumptions explicitly means the team knows where their knowledge gaps are, rather than discovering them late in the project.
The Goal: Zero Open Assumptions
A well-completed solution architecture should have no unresolved assumptions. Every assumption is a statement the team has not yet been able to confirm, and unresolved assumptions mean the architecture is built on uncertain ground.
The Assumptions register exists to make this uncertainty visible — to drive resolution, not to park uncertainty indefinitely. As each assumption is clarified or voided, the architecture becomes more solid and the associated risks reduce.
Why Track Assumptions in an Architecture Repository?
Documenting assumptions in ArchRepo provides:
- Visibility of uncertainty — a central register of everything the team is assuming, visible to architects, project managers, and stakeholders
- Risk quantification — each assumption records what happens if it is wrong, and a risk factor score (0–5) to help prioritise which assumptions to resolve first
- Owner accountability — each assumption has a named owner responsible for driving resolution
- Commercial flagging — assumptions with contractual significance are flagged separately, so commercial and legal reviewers know which assumptions may need to be reflected in contracts
- Traceability to building blocks — when a building block (application, API, service) depends on an assumption being true, that link is documented, making the risk to that component explicit
Assumption Status Lifecycle
Assumptions have their own status lifecycle, separate from the global status mechanism used by other model items.
| Status | Colour | What it means |
|---|---|---|
| Identified | 🔴 Red | The assumption has been recorded but not yet investigated |
| Under Analysis | 🟠 Amber | The team is actively investigating or gathering evidence |
| Waiting (Internal) | 🟡 Yellow | Awaiting a decision or confirmation from within the project or organisation |
| Waiting (External) | 🟡 Yellow | Awaiting input or confirmation from an external party (customer, supplier, regulator) |
| Clarified | 🟢 Green | The assumption has been confirmed or resolved — a clarification has been recorded |
| Void | ⚫ Gray | The assumption is no longer relevant and has been closed without clarification |
The target for every assumption is either Clarified or Void. Any assumption that remains Identified at architecture completion represents an unresolved gap.
Clarification and Building Block Specifications
When an assumption is linked to a building block — such as an Application, API, or backend Service — and that assumption is later Clarified, the clarification record does more than close the assumption. It provides additional specification context for the linked building block.
For example, if an assumption states “We assume the API will support OAuth 2.0 authentication” and that is clarified as confirmed, the clarification record now contains a confirmed requirement that belongs in the API’s specification.
When reviewing the specification of any building block, check its linked assumptions and their clarification records — they often contain decisions and confirmed requirements that are not recorded anywhere else.
Commercial Assumptions
Some assumptions have commercial or contractual significance — they relate to pricing models, service levels, data ownership, licensing terms, or other matters that may be reflected in a contract. These are flagged using the Commercial field.
Commercial assumptions are often tracked in parallel in a formal RAID log or contractual register maintained by the commercial or legal team. Flagging them in ArchRepo ensures the architecture register and the commercial register stay aligned.
Fields Reference
See Assumption Fields for a description of each field and guidance on what to record.