Design Decision Fields

What it’s for: The problem, question, or situation that makes this decision necessary.
What to include:
- What is the problem or challenge being addressed?
- What constraints, pressures, or business drivers apply?
- What is the current state and why is a decision needed?
- Any background context that makes the decision understandable in the future.
Examples:
- "The procurement system needs to notify the ERP when a purchase order is approved. We need to decide whether to use synchronous API calls or asynchronous event-based integration. The ERP vendor has indicated that their API has a 2-second average response time under peak load, which affects the user experience if we use synchronous calls."
- "Legal has confirmed that customer PII cannot leave the UK region. We need to decide how this constraint applies to our analytics data pipeline, which currently sends all event data to a US-hosted data warehouse."

What it’s for: The decision itself — stated clearly and unambiguously.
What to include:
- What was decided. Write it as a statement, not a question.
- Be specific enough that the decision is actionable.
- Avoid hedging — record the decision that was made, not a range of possibilities.
Examples:
- "We will use asynchronous event-based integration via the message queue for all purchase order status notifications to the ERP. Synchronous API calls will not be used for this integration."
- "Customer PII will be excluded from the analytics data pipeline. The data warehouse will receive anonymised event records with a pseudonymous customer identifier only. The mapping between identifiers and customer records will remain in the UK-hosted operational database."

What it’s for: The consequences of the decision — what changes, what trade-offs are accepted, and what the downstream effects are.
What to include:
- What changes as a result of this decision?
- What are the positive consequences? What are the accepted downsides?
- Are there any dependencies or constraints that now follow from this decision?
- What needs to be built, changed, or decommissioned?
Examples:
- "The integration team must implement a message consumer on the ERP side. Notification delivery will be eventually consistent — the ERP will typically receive updates within 5 seconds. The user experience is improved as the approval workflow is no longer blocked by the ERP API response time."
- "Analytics reports will not include customer-level PII. Any future reporting requirement that needs PII data will require a data access process through the operational database, not the data warehouse. This approach is compliant with the UK data residency requirement."

What it’s for: The other options that were evaluated and the reasons they were not chosen.
What to include:
- What alternatives were considered?
- Why was each alternative rejected?
- What trade-offs made the chosen option preferable?
Examples:
- "Synchronous API integration was considered. Rejected because the ERP API response time (avg 2s, peak 8s) would block the approval workflow UI and create a poor user experience. A direct database trigger was also considered but rejected as it would create tight coupling to the ERP database schema."
- "Sending anonymised data to the US data warehouse was considered. Rejected because legal confirmed that even pseudonymous data derived from customer records may constitute personal data under UK GDPR, and the safest interpretation is to exclude it entirely."

What it’s for: A link to any document, presentation, or analysis produced to support or communicate the decision.
What to include:
- Link to a briefing document, options paper, or presentation deck.
- Link to a proof-of-concept report or technical spike output.
- Link to meeting notes or email threads where the decision was agreed.
Examples:
- https://sharepoint.com/sites/project/Shared%20Documents/integration-options-paper.docx
- https://confluence.company.com/display/PRJ/DD-7+Data+Residency+Decision

What it’s for: Any additional commentary, caveats, or follow-up information that does not fit the other fields.
What to include:
- Clarifications added after the decision was recorded.
- References to related decisions.
- Conditions under which the decision should be revisited.

Relationship	What to link
Supports Business Requirement	Business Requirements this decision was made to address or implement
Supports Non-Functional Requirement	NFRs that drove or are addressed by this decision — performance, security, data residency, compliance
Supports Transition Requirement	Transition Requirements this decision addresses — decisions about how the solution moves from current to target state

Relationship	What to link
Has Risk	Risks associated with this decision — risks introduced by the decision, or risks that the decision mitigates
Has Assumption	Assumptions on which this decision depends — if the assumption is invalidated, the decision may need to be revisited
Has Issue	Issues arising from this decision
Has Task	Tasks required to implement or follow up on this decision
Has Acceptance Criteria	Acceptance criteria that verify this decision has been correctly implemented

Relationship	What to link
Implements Business Reference	Standards, policies, or regulatory documents that this decision implements or complies with