What you need to know
The architect who designed a system will not run it forever. A successor who inherits diagrams and code but not the reasons will, sooner or later, "simplify" something that was there for a reason: switch to a global endpoint, remove an approval step, drop a log field. Documentation exists to prevent that, and to let auditors check that controls are real.
The completeness test
Decision logs with rationale
A decision record captures more than the choice:
| Field | Example |
|---|---|
| Decision | Use the cloud platform route with the region set explicitly |
| Alternatives rejected | The global endpoint; the direct API |
| Trade-off resolved | Simpler configuration versus the data-residency obligation |
| Rationale | Customer contracts require in-region processing; the global endpoint could route elsewhere |
| Owner | Platform lead |
| Evidence | Regional configuration export; data-flow record |
| Assumptions | The contract requirement covers logs as well (confirmed by legal, March) |
| Revisit when | A new region is needed, or the provider changes regional options |
The rationale and the rejected alternatives are the most valuable fields for a successor, and the ones most often missing.
Two audiences, different artifacts
| For the person taking over | For the compliance reviewer | |
|---|---|---|
| Explains intent | Architecture diagram, decision log, assumption register | Control register (obligation, control, owner) |
| Shows evidence | Deployment runbook, test and evaluation results | Control register with links to evidence |
| Artifact | Records |
|---|---|
| Assumption register | What is not yet confirmed, and who will confirm it |
| Decision log | What was chosen, what was rejected, and why |
| Architecture diagram | Components, data flows, trust boundaries |
| Runbook | How to deploy, operate, roll back and respond to incidents |
| Evaluation summary | What was tested, on what data, with what results |
| Control register | Obligations mapped to controls, owners and evidence |
Implementation guidance for builders
Handoffs also go forward, to the team that builds. Give them the requirements with sources, the decisions with rationale, the success criteria and evaluation set, interface contracts (tool definitions, schemas), the prompt templates and their versioning rules, and the non-negotiables ("medication lists are inserted by code, never generated"). For AI systems, prompts, model versions and evaluation sets are part of the design and need the same care as code.
Keep it alive
Documentation drifts like configuration. Update the decision log when decisions change, re-date assumptions when confirmed, and plan for known future events, such as a model version being retired, with a note on how to migrate and what to re-evaluate.
In the exam
Documentation questions ask what a handoff package is missing, which artifact serves which audience, or what would have prevented a successor's mistake. The answer is usually the decision log with rationale and rejected alternatives, the assumption register, or the control register with evidence, matched to the audience.
Check your understanding
A successor switches a regulated workload to a global endpoint to simplify configuration, breaking a residency requirement. Which artifact would most likely have prevented this?
Show answer
Answer: D. The successor needed to know that the global endpoint was considered and rejected for a residency reason. Only a decision log with rationale says that.
An auditor asks how the organization knows its human-approval control is working. What should be provided?
Show answer
Answer: C. Auditors need evidence that the control operates, with an owner. Diagrams and designs show intent; pre-launch tests show only a moment in the past.
Which TWO fields make a decision record most useful to a successor?
Show answer
Answer: A, D. Rejected alternatives and rationale tell a successor what not to "simplify" and why.
Apply it: Document Quillstone's in-product assistant
The architect who designed Quillstone's in-product assistant for banks (lessons 3.1 and 3.8) is moving to another team. Prepare the handoff.
- Write three decision records with all the fields in this lesson: the delivery route, per-bank workspaces, and minimal content logging.
Done when: each has rejected alternatives and a rationale. - List four assumptions for the assumption register, with owners.
- List the handoff package for the successor and, separately, what the SOC 2 auditor will receive.
Show model answer
1. Decision records
| Field | Delivery route | Per-bank workspaces | Minimal content logging |
|---|---|---|---|
| Decision | Use the cloud route Quillstone's banks have approved, region set explicitly | One workspace and key per bank, with limits | Log metadata and hashed IDs; sampled, redacted content for 30 days |
| Rejected | Direct API (not on several banks' approved-vendor lists); global endpoint | One shared key with tenant tags | Full transcripts kept for a year |
| Trade-off | Feature timing versus bank procurement and residency | Operational simplicity versus isolation and chargeback | Debugging convenience versus privacy and SOC 2 exposure |
| Rationale | Banks' vendor approvals and contracts decide the route | A shared key lets one bank exhaust limits for all and hides usage | Logs would become the largest store of bank data |
| Owner | Platform lead | Platform lead | Security lead |
| Evidence | Route configuration; bank approval letters | Workspace list; monthly usage reports | Logging configuration; retention job reports |
| Revisit when | A bank requests a new region | Tenant count passes 200 | A regulator or bank requires content retention |
2. Assumptions
| Assumption | Owner |
|---|---|
| No bank requires processing outside its own country | Account management |
| Banks accept usage-based chargeback | Finance |
| 30-day sampled content meets support needs | Support lead |
| The current model version stays available for at least 12 months | Platform lead (track deprecation notices) |
3. Handoff package. For the successor: architecture diagram with trust boundaries, the decision log, the assumption register, prompt templates with version history, the evaluation set and latest results, tool and schema definitions, the runbook (deploy, roll back, tenant onboarding, incident response) and the governance table. For the auditor: the control register (tenant isolation, access control, logging limits, retention, vendor approval) with links to current evidence.