Architecture Decision Records and Risk Documentation

Hello! Last lesson mapped the support-assistant pilot into sources, processing, storage, models, a service, and an agent interface. That map exposed choices the boxes alone cannot settle: where approval state lives, how a withdrawn policy stops appearing as evidence, and which component can prevent an unapproved reply from being sent.

This lesson is about recording such choices without pretending every question is resolved. You’ll see how to write a short architecture decision record (ADR) that explains the decision, its alternatives and consequences, then attach unresolved risks with owners and checks. Allow about 40 minutes for the lesson, including the video and reading.

Record the why, not just the design

Imagine joining the pilot after its first release. You find an application database containing approval records, even though the customer already has a ticket system. Was the extra store necessary because approvals must apply to the final text? Was the ticket system unable to support that rule, or had nobody checked? A component diagram shows what exists; a decision record explains why the team chose it under the conditions known at the time.

Watch CodeOpinion’s Architecture Decision Records (ADR) as a LOG that answers “WHY?” for the purpose and basic shape of an ADR. Skip the tooling demonstration: the aim here is to make decisions reviewable, not to adopt a particular ADR utility.

Not every implementation detail deserves an ADR. “Name this function check_approval” is readily changed and usually needs no architectural review. “Make the application service responsible for verifying final-text approval before sending” affects the service boundary, persisted state, and a customer-facing safeguard. It does.

Microsoft Learn’s Maintain an architecture decision record (ADR) gives a practical threshold for what to record and a concise set of fields. Read it with the pilot in mind: which facts would a future engineer need to assess whether an approval decision still makes sense?

An ADR is a snapshot of reasoning at a point in time. It is not a claim that the design will never change. Preserving the original context makes a later change intelligible: a new requirement, a measured failure, or newly available customer capability may justify a new decision that supersedes the old one.

Give one decision a small, complete record

A useful ADR answers five questions: What problem requires a choice? What matters most? Which realistic options were considered? What is proposed or decided, and why? What becomes better or harder as a result?

The supplied Minimal Architecture Decision Record illustration shows one way to arrange those answers. Its metadata, decision drivers, options, outcome, consequences, and confirmation fields are prompts for thinking, not a demand to fill every box with a paragraph.

For the support assistant, consider where approval state should live for replies that require review. The agreed behavior is narrower than “approve every draft”: the agent controls sending, and a review-required reply needs approval of its final text. Editing after approval must therefore matter. The previous architecture map identified a possible application store but did not establish that it is authorized or necessary.

Here is a concise proposed record. It describes a design for discussion, not an approval already granted by the customer.

ADR-007: Verify final-text approval in the application send service
Status: Proposed
Record owner: Delivery engineer; customer decision owner and reviewers to be confirmed.

Context and drivers. Agents may edit drafts. For review-required replies, approval of an earlier version must not authorize sending edited text. The pilot must also avoid retaining unnecessary ticket content and must not imply that a model can enforce approval.

Options considered.

1. Use the ticket system’s approval state alone. This avoids a new store, but we have not established whether it identifies the exact approved text or whether the assistant can verify it at send time.
2. Keep a minimal application-owned approval record and check it in the application send service. This supports a final-text check but adds storage, access-control, and retention responsibilities.
3. Leave sending entirely outside the assistant for the pilot. This reduces integration work but cannot, by itself, demonstrate that the assistant’s send path enforces the agreed rule.

Proposed decision and rationale. For review-required replies, the application send service will check an approval record against the final text presented for sending. The proposed record contains a ticket reference, approval status, approver identity, and an identifier or fingerprint for the approved text—not a second full copy of the reply. A changed final text requires new approval. Adopt this option only if the customer confirms the send path and permits the proposed approval data to be retained.

Consequences. The send check can reject a stale approval, including after an agent edit. In return, the application owns approval-state security, retention, and failure handling. If approval state cannot be verified, the assistant must not present a successful send. This record does not settle who may approve or how long the metadata may be kept.

Confirmation before acceptance. Confirm the authorized approver role and permitted retention; establish that every assistant-initiated send uses this service; demonstrate in a test environment that an approved reply can be sent but an edited version cannot be sent under the old approval.

Notice what the record does not do. It does not select a database product, specify a schema, or claim the ticket system lacks a capability nobody has checked. It makes the choice and its conditions legible. If investigation shows that the ticket system can verify approval of the exact final text through the required send path, option 1 may become preferable.

Status carries meaning. “Proposed” invites review; it is not permission to build an unapproved customer-facing send feature. Once the authorized decision makers accept a record, retain its rationale. If later evidence changes the direction, write a new, linked record that supersedes it rather than silently rewriting what the team originally decided.

Keep unresolved risks visible and actionable

An unresolved question is easy to bury in a sentence such as “confirm integration later.” A useful risk entry states what may be false, what would happen, who will obtain evidence, when a decision is needed, and what remains safe meanwhile. This separates the proposed choice from the evidence still needed to accept or deploy it.

The proposed ADR has at least two material risks:

These entries do not require the team to predict that failure will occur. They identify uncertainties whose impact is large enough to affect the decision. An owner is responsible for producing an answer, not for guaranteeing a favorable answer. A gate specifies when that answer must exist; a safeguard says what the pilot will refrain from doing while it does not.

Keep distinct risks distinct. Policy-index freshness, identified in the previous lesson, is important—but it concerns the preparation and retrieval path, not the location of final-text approval state. It may need its own decision or tracked risk, with a policy owner to set the acceptable delay before withdrawn material becomes unusable. Packing every architectural uncertainty into ADR-007 would make its decision difficult to find.

The same discipline helps with customer conversations. A statement such as “the system uses an application approval store” sounds settled. “We propose an application approval record because approval must match final text; the ticket-system capability and retention permission remain to be confirmed” conveys both a defensible direction and its limits.

Conclusion

A concise decision record preserves the problem, drivers, alternatives, justified choice, status, and consequences of one significant architectural decision. Record unresolved risks beside it with an evidence owner, a decision gate, and a safe interim position. That combination lets a team move forward where it can without disguising assumptions as customer-approved facts.

Next lesson, you’ll use this clarity to define a thin vertical slice: a small end-to-end implementation chosen to test a high-risk assumption before committing to the broader solution.