Architecture Starts With a Conversation, Not a Document
Architecture starts as a conversation, not a form. Seven document types, one question each, and the full template for each.
On our project tracker, a team couldn't move work into Active without filling in two required fields: who approved the architecture, and the date they approved it. On paper, nothing started without an architecture review. In practice, the tracker only checked that those two boxes weren't blank.
Eighty-three items carry that date. Twenty of them share one date. Some of those are mine: the migration that moved the items onto architecture's board wrote my name and its own date. Delivery teams filled in the rest. I can't tell you whether a real decision sits behind any of them, and neither can the field. That's the problem.
If those were backfilled, it's a team being rational about a gate. Put a field in the way of progress and the field gets filled in. So what's the cheapest way to fill it? A plausible value nobody has to defend.
So don't build a gate. Build a language. An architecture function earns its authority by unblocking, and everything in this series comes back to that sentence. None of it works until the teams you're trying to help can understand you, and that shared understanding is a language. In this job, the language is documents.
Enterprise Architecture By Hand is a five-part guide to running an architecture function with no mandate, no budget and no title. It's for the staff engineer, principal or tech lead who will do it anyway. Each part ends with something you can do the same week; this one ends with seven document types and the full template for each.
The seven document types
Seven document types carry our framework, one question each. Keep the split clean and the rest follows.
Request for comments (RFC): should we do this? Short, ephemeral, and collaborative: it gathers advice on a significant change before a decision is made, then resolves into an ADR or closes.
Architecture decision record (ADR): what did we choose, and why? Write the decision once, when it lands, then never edit the decision. The one edit a record allows is the Superseded by line, naming the later record that replaced it. Change your mind and you write a new record.
Solution architecture document (SAD), the design doc: what is the target state? This one stays alive as the umbrella for a program spanning multiple statements of work, beside the code it describes, because the code is what makes it wrong first.
Standard (STD): what are the rules today? The living rulebook that codifies durable rules produced by accepted ADRs: the ADRs hold the why, and this document holds the what.
Runbook (RUN): how do I do it? A procedural, step-by-step operational guide with verification and rollback, implementing the rules that live in standards.
Statement of work (SOW): what are we delivering? A bounded delivery document that pairs deliverables with acceptance criteria and a minimum viable solution floor, from start to done.
Opportunity brief (BRIEF): why fund this? A one-page executive pitch in business terms (the problem, the cost of doing nothing, the options, the ask, and the success measures) whose only job is to win sponsorship and spawn a SAD.
Each of the seven questions has its own lifecycle: ephemeral, frozen, or living.
- Ephemeral: two proposals that do their job and stop. The RFC ("should we do this?") gathers advice until it resolves into an ADR or closes and freezes, and the BRIEF ("why fund this?") pitches the business case in one page until it is funded or parked and spawns a SAD or SOW.
- Frozen: two records that do not get rewritten. The ADR ("what did we choose, and why?") is immutable once accepted, never edited except to name the record that superseded it, and the SOW ("what are we delivering?") bounds a delivery and is frozen at done.
- Living: three documents that evolve with the system. The SAD ("what is the target state?") updates as decisions land, the STD ("what are the rules today?") is versioned and reviewed on cadence, and the RUN ("how do I do it?") is tested in exercises or incidents and archived when it goes stale.
If your company has better names for the seven, use those instead, because the words matter less than the questions.
How the seven fit together
Three flows run through it. Money flows left to right: a brief gets funded, a SAD defines the target, SOWs deliver it. Decisions flow up: an RFC resolves into an ADR, and the ADR rolls up to the SAD. Rules flow on from there: accepted ADRs get codified into a standard, and runbooks apply it. The dashed line is the one people skip: when a big decision surfaces mid-delivery, it leaves the SOW and goes through an RFC.
The seven templates
The full templates, ready to copy. They're long because a template isn't a summary. Each one opens with an HTML comment for AI assistants, invisible when rendered: delete it before you publish, or keep it if your team drafts with one.
Request for comments (RFC)
---
id: RFC-NNNN
title: "[Short proposal title]"
status: draft # draft | open-for-advice | resolved | closed
author: "[Proposing engineer(s)]"
sponsor: "[Tech lead helping guide the proposal. Recruit one early]"
affected_teams: [] # every team this touches: your advice audience
feedback_deadline: YYYY-MM-DD # default: two weeks from opening
review_session: YYYY-MM-DD # architecture forum slot, if needed
resulting_adr: "" # ADR-NNNN once resolved, or "N/A, closed"
related: [] # SAD / SOW this proposal affects
ai_assistance: none # or "AI-assisted draft, reviewed by [Name] on YYYY-MM-DD"
---
<!--
For AI assistants. This is a Request for Comments: an ephemeral proposal answering
"should we do this?". It gathers advice, then resolves into an ADR or closes, and is frozen.
Rules: keep must-haves separate from the preferred approach. Draft open questions, not
conclusions. Add advice rows only for real, named people the human relays. Keep it short
enough to review in one sitting.
Ground truth: fill a field only from what the human told you or gave you. If it's missing,
keep the [placeholder] and ask. A blank field is correct; an invented one is a defect.
Ask: Which teams are affected? What spikes or evidence exist? What feedback deadline?
-->
# RFC: [Short proposal title]
An RFC gathers advice on a significant change before any decision is made. Anyone may open one. It resolves into an ADR or closes, and is then frozen.
> **This is not a decision.** This document gathers advice on what to do; the ADR records what was decided and why. The feedback deadline is real: an RFC without one is where ideas go to die.
## 01 · Problem / opportunity
Why this proposal exists and why now, in terms an affected team recognizes: a pain point, a deadline, a new constraint, an opportunity.
[What is the situation, and what happens if nothing changes?]
## 02 · Proposal
Detailed enough to give advice on, not an implementation spec.
### Must-haves
Properties any acceptable solution needs, kept apart from the approach so advisors can challenge one without losing the other.
- [Property any acceptable solution must satisfy]
- [...]
### Proposed approach
[The change being proposed. A Mermaid sketch is welcome; it freezes with the RFC at resolution.]
## 03 · Alternatives considered (optional)
One line per option is enough. The full trade-off analysis happens in the ADR once advice is in.
- [Alternative A: one line on why it is not preferred]
- [Do nothing: what the status quo costs]
## 04 · Impact, risks and spikes
| Aspect | Detail |
|---|---|
| Affected parties | [Teams / systems touched, and how] |
| Risks | [What could go wrong; security or compliance implications] |
| Spikes / evidence | [Experiments run or needed; link the findings] |
| Cost signal | [Rough order of magnitude: licence, effort, run cost] |
## 05 · Advice and feedback
The working surface of the RFC. Advisors add rows; the author answers every one. When the RFC resolves, this table seeds the ADR's advice section.
| Advisor / role | Feedback | Response (adopted / adapted / declined: why) |
|---|---|---|
| [Name, role] | [Concern, suggestion, or red flag] | [Disposition and reason] |
> **Resolving debates.** Most advice resolves asynchronously in the table. If a debate is still open near the deadline, book a slot at the architecture forum rather than extending the deadline: extension is how proposals stall.
## 06 · Resolution
Filled once, then frozen. Capture the reason, so the idea isn't re-litigated from scratch next year.
| Field | Detail |
|---|---|
| Outcome | [Resolved → ADR-NNNN / Closed] |
| Rationale | [One paragraph: why this outcome] |
| Date | [YYYY-MM-DD] |
id: RFC-NNNN title: "[Short proposal title]" status: draft # draft | open-for-advice | resolved | closed author: "[Proposing engineer(s)]" sponsor: "[Tech lead helping guide the proposal. Recruit one early]" affected_teams: [] # every team this touches: your advice audience feedback_deadline: YYYY-MM-DD # default: two weeks from opening review_session: YYYY-MM-DD # architecture forum slot, if needed resulting_adr: "" # ADR-NNNN once resolved, or "N/A, closed" related: [] # SAD / SOW this proposal affects ai_assistance: none # or "AI-assisted draft, reviewed by [Name] on YYYY-MM-DD"
<!-- For AI assistants. This is a Request for Comments: an ephemeral proposal answering "should we do this?". It gathers advice, then resolves into an ADR or closes, and is frozen. Rules: keep must-haves separate from the preferred approach. Draft open questions, not conclusions. Add advice rows only for real, named people the human relays. Keep it short enough to review in one sitting. Ground truth: fill a field only from what the human told you or gave you. If it's missing, keep the [placeholder] and ask. A blank field is correct; an invented one is a defect. Ask: Which teams are affected? What spikes or evidence exist? What feedback deadline? -->
RFC: [Short proposal title]
An RFC gathers advice on a significant change before any decision is made. Anyone may open one. It resolves into an ADR or closes, and is then frozen.
This is not a decision. This document gathers advice on what to do; the ADR records what was decided and why. The feedback deadline is real: an RFC without one is where ideas go to die.
01 · Problem / opportunity
Why this proposal exists and why now, in terms an affected team recognizes: a pain point, a deadline, a new constraint, an opportunity.
[What is the situation, and what happens if nothing changes?]
02 · Proposal
Detailed enough to give advice on, not an implementation spec.
Must-haves
Properties any acceptable solution needs, kept apart from the approach so advisors can challenge one without losing the other.
- [Property any acceptable solution must satisfy]
- [...]
Proposed approach
[The change being proposed. A Mermaid sketch is welcome; it freezes with the RFC at resolution.]
03 · Alternatives considered (optional)
One line per option is enough. The full trade-off analysis happens in the ADR once advice is in.
- [Alternative A: one line on why it is not preferred]
- [Do nothing: what the status quo costs]
04 · Impact, risks and spikes
| Aspect | Detail |
|---|---|
| Affected parties | [Teams / systems touched, and how] |
| Risks | [What could go wrong; security or compliance implications] |
| Spikes / evidence | [Experiments run or needed; link the findings] |
| Cost signal | [Rough order of magnitude: licence, effort, run cost] |
05 · Advice and feedback
The working surface of the RFC. Advisors add rows; the author answers every one. When the RFC resolves, this table seeds the ADR's advice section.
| Advisor / role | Feedback | Response (adopted / adapted / declined: why) |
|---|---|---|
| [Name, role] | [Concern, suggestion, or red flag] | [Disposition and reason] |
Resolving debates. Most advice resolves asynchronously in the table. If a debate is still open near the deadline, book a slot at the architecture forum rather than extending the deadline: extension is how proposals stall.
06 · Resolution
Filled once, then frozen. Capture the reason, so the idea isn't re-litigated from scratch next year.
| Field | Detail |
|---|---|
| Outcome | [Resolved → ADR-NNNN / Closed] |
| Rationale | [One paragraph: why this outcome] |
| Date | [YYYY-MM-DD] |
Architecture decision record (ADR)
---
id: ADR-NNNN # claimed from the ADR folder; never guess the next number
title: "[Short, present-tense decision title]"
status: proposed # proposed | accepted | deprecated | superseded
owning_team: "[Team / domain making the decision]"
author: "[Name, role]"
supersedes: none # ADR-NNNN or none
superseded_by: none
related_rfc: "" # or "none, direct to ADR"
related_sad: ""
related_sows: []
date_proposed: YYYY-MM-DD
date_decided: YYYY-MM-DD
ai_assistance: none
---
<!--
For AI assistants. This is an Architecture Decision Record: an immutable, point-in-time
record answering "what did we choose, and why?". Once accepted it is never edited, only
superseded by a new ADR.
Rules: write Context value-neutral (facts, forces, constraints; the tension, not the answer).
Give negative consequences equal weight: an ADR that lists no costs is unfinished. Add advice
rows only for consultations the human reports. Embed diagrams as Mermaid or a static export
frozen at decision time; no live diagram links.
Ground truth: fill a field only from what the human told you or gave you; otherwise keep the
[placeholder] and ask.
Ask: Who was consulted, and what did each say? Which alternatives were seriously evaluated,
including doing nothing? What is the single strongest reason for the chosen option?
-->
# ADR-NNNN: [Short, present-tense decision title]
One ADR, one decision. Once accepted, don't rewrite it: supersede it with a new ADR.
## 01 · Context
The forces at play (technical, business, organizational, security, project-local) and the tension between them. A reader six months from now should understand the situation without already knowing the outcome. Focus on the why, not the what.
- [What is the situation? What constraints, deadlines, or existing systems are in play?]
- [What tensions exist: speed vs. cost, build vs. buy, flexibility vs. simplicity?]
- [Why does this decision need to be made now? What is the trigger?]
## 02 · Decision drivers (optional)
The criteria the decision is judged against. Listing them up front makes the comparison defensible.
- [e.g. operational cost ceiling of $X / month]
- [e.g. must integrate with the existing infrastructure-as-code stack]
- [e.g. auditability / data residency requirement]
- [e.g. team familiarity / time to delivery]
## 03 · Considered alternatives
Every option seriously evaluated, including doing nothing. The chosen option goes here too; the Decision section only commits to it.
- **A · [Name]:** [One-line description]
- **B · [Name]:** [One-line description]
- **C · Do nothing:** [What happens if we make no change]
| Alternative | Pros | Cons | Verdict |
|---|---|---|---|
| [A · Name] | [Key strengths] | [Key weaknesses / risks] | [Chosen / Rejected] |
| [B · Name] | [...] | [...] | [...] |
| [C · Status quo] | [...] | [...] | [...] |
## 04 · Advice sought
Everyone affected and everyone with relevant expertise who was consulted, what they said, and how it was handled. Advice comes before acceptance: an unconsulted affected party is a process failure.
| Advisor / role | Advice given | Disposition (adopted / adapted / declined: why) |
|---|---|---|
| [Name, role / why consulted] | [Summary of the advice] | [...] |
## 05 · Decision
In full sentences and active voice. Specific enough to act on: vague decisions aren't decisions.
[We will adopt [Alternative X] because [primary justification].]
[Scope: where this applies, and where it explicitly does not.]
> **Diagrams here are frozen.** Embed Mermaid source or a static export captured at decision time. If a live board is useful, link it separately and label it "current state".
## 06 · Consequences
Every consequence shapes the team and the system. Negative ones aren't a sign of a bad decision; hiding them is.
- **Positive:** [What gets better or becomes possible]
- **Negative:** [What gets harder; the cost or risk we accept]
- **Neutral:** [Side effects worth recording]
### Follow-up actions (optional)
- [New ADRs, SOWs to spin up, deprecations to schedule, owners to notify]
> **Review before accepting.** An accepted ADR cannot be rewritten. Confirm every affected party was asked (§04) before you change the status.
## 07 · Compliance and validation (optional)
- [How conformance is checked: CI policy, IaC module, lint rule, review gate]
- [What signal tells us the decision was right or wrong: metric, SLO, cost line, incident class]
## 08 · References (optional)
- [Prior ADRs, parent SAD, spikes, vendor docs, benchmarks, incident reports]id: ADR-NNNN # claimed from the ADR folder; never guess the next number title: "[Short, present-tense decision title]" status: proposed # proposed | accepted | deprecated | superseded owning_team: "[Team / domain making the decision]" author: "[Name, role]" supersedes: none # ADR-NNNN or none superseded_by: none related_rfc: "" # or "none, direct to ADR" related_sad: "" related_sows: [] date_proposed: YYYY-MM-DD date_decided: YYYY-MM-DD ai_assistance: none
<!-- For AI assistants. This is an Architecture Decision Record: an immutable, point-in-time record answering "what did we choose, and why?". Once accepted it is never edited, only superseded by a new ADR. Rules: write Context value-neutral (facts, forces, constraints; the tension, not the answer). Give negative consequences equal weight: an ADR that lists no costs is unfinished. Add advice rows only for consultations the human reports. Embed diagrams as Mermaid or a static export frozen at decision time; no live diagram links. Ground truth: fill a field only from what the human told you or gave you; otherwise keep the [placeholder] and ask. Ask: Who was consulted, and what did each say? Which alternatives were seriously evaluated, including doing nothing? What is the single strongest reason for the chosen option? -->
ADR-NNNN: [Short, present-tense decision title]
One ADR, one decision. Once accepted, don't rewrite it: supersede it with a new ADR.
01 · Context
The forces at play (technical, business, organizational, security, project-local) and the tension between them. A reader six months from now should understand the situation without already knowing the outcome. Focus on the why, not the what.
- [What is the situation? What constraints, deadlines, or existing systems are in play?]
- [What tensions exist: speed vs. cost, build vs. buy, flexibility vs. simplicity?]
- [Why does this decision need to be made now? What is the trigger?]
02 · Decision drivers (optional)
The criteria the decision is judged against. Listing them up front makes the comparison defensible.
- [e.g. operational cost ceiling of $X / month]
- [e.g. must integrate with the existing infrastructure-as-code stack]
- [e.g. auditability / data residency requirement]
- [e.g. team familiarity / time to delivery]
03 · Considered alternatives
Every option seriously evaluated, including doing nothing. The chosen option goes here too; the Decision section only commits to it.
- A · [Name]: [One-line description]
- B · [Name]: [One-line description]
- C · Do nothing: [What happens if we make no change]
| Alternative | Pros | Cons | Verdict |
|---|---|---|---|
| [A · Name] | [Key strengths] | [Key weaknesses / risks] | [Chosen / Rejected] |
| [B · Name] | [...] | [...] | [...] |
| [C · Status quo] | [...] | [...] | [...] |
04 · Advice sought
Everyone affected and everyone with relevant expertise who was consulted, what they said, and how it was handled. Advice comes before acceptance: an unconsulted affected party is a process failure.
| Advisor / role | Advice given | Disposition (adopted / adapted / declined: why) |
|---|---|---|
| [Name, role / why consulted] | [Summary of the advice] | [...] |
05 · Decision
In full sentences and active voice. Specific enough to act on: vague decisions aren't decisions.
[We will adopt [Alternative X] because [primary justification].]
[Scope: where this applies, and where it explicitly does not.]
Diagrams here are frozen. Embed Mermaid source or a static export captured at decision time. If a live board is useful, link it separately and label it "current state".
06 · Consequences
Every consequence shapes the team and the system. Negative ones aren't a sign of a bad decision; hiding them is.
- Positive: [What gets better or becomes possible]
- Negative: [What gets harder; the cost or risk we accept]
- Neutral: [Side effects worth recording]
Follow-up actions (optional)
- [New ADRs, SOWs to spin up, deprecations to schedule, owners to notify]
Review before accepting. An accepted ADR cannot be rewritten. Confirm every affected party was asked (§04) before you change the status.
07 · Compliance and validation (optional)
- [How conformance is checked: CI policy, IaC module, lint rule, review gate]
- [What signal tells us the decision was right or wrong: metric, SLO, cost line, incident class]
08 · References (optional)
- [Prior ADRs, parent SAD, spikes, vendor docs, benchmarks, incident reports]
Solution architecture document (SAD)
---
id: SAD-NNNN
title: "[Program name]"
status: draft # draft | in-review | approved
version: 0.1
owning_team: "[Lead team / domain]"
author: "[Name, role]"
sponsor: "[Executive sponsor, title]"
originating_brief: "" # the BRIEF that won sponsorship, or "N/A"
related_adrs: []
related_sows: []
related_rfcs: []
last_updated: YYYY-MM-DD
ai_assistance: none
---
<!--
For AI assistants. This is a Solution Architecture Document: the living umbrella for a program
spanning multiple SOWs, answering "what is the target state?". It evolves as decisions are made.
Rules: keep the Executive Summary readable by a non-technical sponsor. Map every capability row
to a SOW; an unmapped capability is an open question. Live diagrams belong here; frozen views
belong in ADRs. Ask for concrete ADR, SOW and BRIEF IDs instead of leaving brackets.
Ground truth: fill a field only from what the human told you or gave you; otherwise keep the
[placeholder] and ask.
Ask: Which accepted ADRs already constrain this program? What is out of scope? Which
capabilities become which SOWs, and in what order?
-->
# SAD: [Program name]
The umbrella architecture for a program that spans multiple SOWs: target state, principles, capability decomposition, key decisions. SOWs deliver the components; ADRs record the decisions and link back here. Keep it alive: the diagram is authoritative for structure, the prose for rationale.
## 01 · Executive summary
[2–4 sentences a non-technical sponsor can read: what changes, who benefits, when we get there.]
## 02 · Business context and drivers
Why this program exists, and what happens if we do nothing.
- [Driver, e.g. end-of-life vendor contract / compliance gap]
- [Driver, e.g. cost reduction target of $X]
**Strategic alignment:** [How this ties to company goals, tech strategy, or regulatory commitments.]
## 03 · Current state
| Component | Purpose | Owner | Disposition |
|---|---|---|---|
| [Component A] | [What it does today] | [Team] | [Replace / Retain / Retire] |
**Known pain points**
- [Pain point]
## 04 · Target state
[Embed C4 context and container diagrams, or equivalent. Logical view first, deployment view second.]
| Component | Responsibility | Technology |
|---|---|---|
| [Component] | [What it does, what it owns] | [e.g. secrets manager] |
## 05 · Architecture principles
Non-negotiable rules every SOW respects. Keep it to five to eight.
| Principle | Implication | Anti-pattern |
|---|---|---|
| Identity is the perimeter | Every secret access is authenticated via SSO/OIDC and audited | Static API keys, shared service accounts |
| [Principle] | [...] | [...] |
## 06 · Capability decomposition → SOW map
The bridge between this document and delivery: each row is, or will become, one SOW.
| Capability | Description | SOW | Phase |
|---|---|---|---|
| [Capability] | [What it provides] | [SOW-A] | [Phase 1] |
## 07 · Cross-cutting concerns
Every SOW inherits these rather than redefining them.
- **Security and compliance:** [Threat model, applicable controls, data classification, encryption, audit trail]
- **Identity and access:** [Identity provider, MFA, break-glass procedure, role model]
- **Observability:** [Logging, metrics, SLO catalogue, alert routing. SOWs MUST emit these signals]
- **Reliability and DR:** [RPO / RTO, multi-region posture, failover model]
- **Cost model:** [Funding source, run rate, showback, cost guardrails]
## 08 · Key architecture decisions
Each row links to a standalone ADR; summaries only here. Every linked ADR must be accepted, and the architecture reviewed, before implementation begins.
| ADR | Decision | Chosen option | Status | Date |
|---|---|---|---|---|
| [ADR-0001] | [Decision title] | [Chosen option] | [Accepted] | [YYYY-MM-DD] |
## 09 · Roadmap and phasing
Each phase has an exit criterion that gates the next.
| Phase | Outcome | SOWs | Exit criteria |
|---|---|---|---|
| 1: Foundation | [Outcome] | [SOW-A, SOW-B] | [Measurable exit] |
| 2: Expansion | [...] | [...] | [...] |
| 3: Decommission | [Legacy retired] | [SOW-N] | [Contracts terminated, traffic at zero] |
## 10 · Dependencies
- **External:** [Vendor / SaaS: version, contract status, support level; regulatory dependencies]
- **Internal:** [Teams, systems, shared platform components]
## 11 · Risks and mitigations
Validate every change against regulatory, compliance and security requirements before implementation.
| Risk | Likelihood | Impact | Mitigation / owner |
|---|---|---|---|
| [Risk] | [L / M / H] | [L / M / H] | [Plan, owner] |
## 12 · Assumptions
- [Assumption]
## 13 · Out of scope
What people might expect here but is excluded. This is what stops scope creep at the SOW level.
- [Excluded item, and why]
## 14 · Glossary
| Term | Definition |
|---|---|
| [Term a new joiner would have to look up] | [Plain-language definition] |
## 15 · References
- [Vendor evaluation, threat model, cost model]id: SAD-NNNN title: "[Program name]" status: draft # draft | in-review | approved version: 0.1 owning_team: "[Lead team / domain]" author: "[Name, role]" sponsor: "[Executive sponsor, title]" originating_brief: "" # the BRIEF that won sponsorship, or "N/A" related_adrs: [] related_sows: [] related_rfcs: [] last_updated: YYYY-MM-DD ai_assistance: none
<!-- For AI assistants. This is a Solution Architecture Document: the living umbrella for a program spanning multiple SOWs, answering "what is the target state?". It evolves as decisions are made. Rules: keep the Executive Summary readable by a non-technical sponsor. Map every capability row to a SOW; an unmapped capability is an open question. Live diagrams belong here; frozen views belong in ADRs. Ask for concrete ADR, SOW and BRIEF IDs instead of leaving brackets. Ground truth: fill a field only from what the human told you or gave you; otherwise keep the [placeholder] and ask. Ask: Which accepted ADRs already constrain this program? What is out of scope? Which capabilities become which SOWs, and in what order? -->
SAD: [Program name]
The umbrella architecture for a program that spans multiple SOWs: target state, principles, capability decomposition, key decisions. SOWs deliver the components; ADRs record the decisions and link back here. Keep it alive: the diagram is authoritative for structure, the prose for rationale.
01 · Executive summary
[2–4 sentences a non-technical sponsor can read: what changes, who benefits, when we get there.]
02 · Business context and drivers
Why this program exists, and what happens if we do nothing.
- [Driver, e.g. end-of-life vendor contract / compliance gap]
- [Driver, e.g. cost reduction target of $X]
Strategic alignment: [How this ties to company goals, tech strategy, or regulatory commitments.]
03 · Current state
| Component | Purpose | Owner | Disposition |
|---|---|---|---|
| [Component A] | [What it does today] | [Team] | [Replace / Retain / Retire] |
Known pain points
- [Pain point]
04 · Target state
[Embed C4 context and container diagrams, or equivalent. Logical view first, deployment view second.]
| Component | Responsibility | Technology |
|---|---|---|
| [Component] | [What it does, what it owns] | [e.g. secrets manager] |
05 · Architecture principles
Non-negotiable rules every SOW respects. Keep it to five to eight.
| Principle | Implication | Anti-pattern |
|---|---|---|
| Identity is the perimeter | Every secret access is authenticated via SSO/OIDC and audited | Static API keys, shared service accounts |
| [Principle] | [...] | [...] |
06 · Capability decomposition → SOW map
The bridge between this document and delivery: each row is, or will become, one SOW.
| Capability | Description | SOW | Phase |
|---|---|---|---|
| [Capability] | [What it provides] | [SOW-A] | [Phase 1] |
07 · Cross-cutting concerns
Every SOW inherits these rather than redefining them.
- Security and compliance: [Threat model, applicable controls, data classification, encryption, audit trail]
- Identity and access: [Identity provider, MFA, break-glass procedure, role model]
- Observability: [Logging, metrics, SLO catalogue, alert routing. SOWs MUST emit these signals]
- Reliability and DR: [RPO / RTO, multi-region posture, failover model]
- Cost model: [Funding source, run rate, showback, cost guardrails]
08 · Key architecture decisions
Each row links to a standalone ADR; summaries only here. Every linked ADR must be accepted, and the architecture reviewed, before implementation begins.
| ADR | Decision | Chosen option | Status | Date |
|---|---|---|---|---|
| [ADR-0001] | [Decision title] | [Chosen option] | [Accepted] | [YYYY-MM-DD] |
09 · Roadmap and phasing
Each phase has an exit criterion that gates the next.
| Phase | Outcome | SOWs | Exit criteria |
|---|---|---|---|
| 1: Foundation | [Outcome] | [SOW-A, SOW-B] | [Measurable exit] |
| 2: Expansion | [...] | [...] | [...] |
| 3: Decommission | [Legacy retired] | [SOW-N] | [Contracts terminated, traffic at zero] |
10 · Dependencies
- External: [Vendor / SaaS: version, contract status, support level; regulatory dependencies]
- Internal: [Teams, systems, shared platform components]
11 · Risks and mitigations
Validate every change against regulatory, compliance and security requirements before implementation.
| Risk | Likelihood | Impact | Mitigation / owner |
|---|---|---|---|
| [Risk] | [L / M / H] | [L / M / H] | [Plan, owner] |
12 · Assumptions
- [Assumption]
13 · Out of scope
What people might expect here but is excluded. This is what stops scope creep at the SOW level.
- [Excluded item, and why]
14 · Glossary
| Term | Definition |
|---|---|
| [Term a new joiner would have to look up] | [Plain-language definition] |
15 · References
- [Vendor evaluation, threat model, cost model]
Standard (STD)
---
id: STD-NNNN # claimed from the standards folder; never guess the next number
title: "[Short, imperative title, e.g. Server Hardening Baseline]"
status: draft # draft | in-review | active | superseded | retired
version: 1.0
owner: "[Named person accountable for currency: a person, not a team]"
review_team: "[Security, affected platform teams, compliance where applicable]"
author: "[Name, role]"
source_adrs: [] # REQUIRED: the accepted ADRs that justify this standard
supersedes: none
superseded_by: none
compliance_mappings: [] # e.g. PCI DSS, NIST 800-53, CIS, your regional regulators
review_cadence: annual # minimum, plus the out-of-cycle triggers in §07
next_review: YYYY-MM-DD
last_updated: YYYY-MM-DD
ai_assistance: none
---
<!--
For AI assistants. This is a Standard: the living rulebook answering "what are the rules
today?". Versioned, owned, reviewed on cadence, machine-verified where possible.
Rules: exactly one capitalized RFC 2119 keyword per control. Complete each control row:
requirement, mapping, verification, evidence. If a control can't be tied to a source ADR,
flag the gap and suggest an RFC: write no unjustified rules. Keep procedures out; they
belong in a runbook.
Ground truth: fill a field only from what the human told you or gave you; otherwise keep the
[placeholder] and ask.
Ask: Which accepted ADRs justify these controls? How is each control verified by machine,
and where do results land? Which compliance frameworks must the mapping cover?
-->
# STD-NNNN: [Short, imperative title]
The living rulebook. ADRs hold the why; this holds the what. One standard, one control domain.
> **The justification test.** Every standard cites the accepted ADRs that produced it. If no ADR can justify a rule, question whether the rule should exist. A standard with no source ADRs does not pass review.
## 01 · Purpose and scope
[The risk or inconsistency this standard removes, and the position the organization takes.]
| Boundary | Definition |
|---|---|
| In scope | [Systems, environments, accounts, e.g. "all production server instances"] |
| Out of scope | [Exclusions, and the standard that covers them] |
## 02 · Roles and responsibilities
| Role | Responsibility |
|---|---|
| Standard owner | Keeps it current, runs the review cycle, owns the exception register |
| Review team | Validates operational feasibility and compliance alignment at each review |
| Enforcing teams | Implement and operate the controls |
| All engineers | Comply with MUST controls; request an exception when they can't |
## 03 · Requirement language (RFC 2119)
Every control uses exactly one of these, capitalized.
| Keyword | Meaning |
|---|---|
| MUST / SHALL | Absolute requirement. Non-compliance needs an approved, time-boxed exception (§05) |
| MUST NOT | Absolute prohibition. Same exception process |
| SHOULD | Strong recommendation. Deviation needs a documented justification |
| MAY | Genuinely optional, once every MUST and SHOULD is met |
## 04 · Controls
Number controls STD-NNNN-CC and group them by function. This section says what must be true, not how: procedures belong in a linked runbook, so the rules stay stable while the procedures evolve.
### [Control group A, e.g. Authentication and access]
| ID | Requirement | Mapping | Verification | Evidence |
|---|---|---|---|---|
| STD-NNNN-01 | [All administrative sessions MUST enforce MFA] | [NIST IA-2; PCI DSS 8.4] | [Query sign-in logs for admin roles] | [Exported policy; sign-in log sample] |
| STD-NNNN-02 | [Data at rest SHOULD be encrypted with AES-256] | [NIST SC-28] | [Config rule / volume encryption query] | [Generated config report; key rotation logs] |
### [Control group B, e.g. Logging and monitoring]
| ID | Requirement | Mapping | Verification | Evidence |
|---|---|---|---|---|
| STD-NNNN-11 | [...] | [...] | [...] | [...] |
## 05 · Exceptions
A controlled, time-boxed deviation with explicit risk acceptance. Indefinite waivers quietly accumulate risk debt.
1. Every exception MUST be time-boxed: 12 months maximum, shorter where the remediation plan allows.
2. Every exception MUST name a risk owner with the authority to accept the risk. Approving one is accepting a risk, not granting a bypass.
3. Every exception MUST define compensating controls and a remediation plan.
4. 90 days before expiry, the submitter is asked for a status update; renewal runs an abbreviated approval.
5. An exception that lapses without review is a governance failure, and is escalated as one.
6. Approval scales with blast radius: one team → standard owner; cross-team or compliance-relevant → architecture forum; enterprise or regulatory exposure → CISO or executive risk owner.
> **Compensating controls** must meet the intent and rigor of the original requirement, defend against the same risk, go beyond what other controls already require, and cover the extra risk of the deviation for its full duration. "We accept the risk" is not a compensating control.
| ID | Scope | Risk owner | Compensating controls | Approved by | Expires | Status |
|---|---|---|---|---|---|---|
| EX-01 | [Systems / controls excepted] | [Name, role] | [Mitigations in place] | [Name] | [YYYY-MM-DD] | [Active / Expired / Closed] |
## 06 · Verification and drift detection
Check adherence continuously, not only at review time. Prefer policy-as-code and scheduled scans over manual attestation.
| Aspect | Definition |
|---|---|
| Method | [e.g. config rules, compliance policies, scheduled benchmark scans] |
| Cadence | [Continuous / daily / weekly, per control group] |
| Results land in | [Dashboard / SIEM / compliance report] |
| Drift response | [Auto-remediate / ticket / escalate, by criticality] |
## 07 · Review and maintenance
Reviewed at least annually, plus out of cycle when triggered by:
- A major architectural change in the control domain
- A new or changed regulatory requirement
- Relevant threat intelligence
- A newly accepted ADR that supersedes or amends a source ADR
| Version | Date | Author | Change |
|---|---|---|---|
| 1.0 | [YYYY-MM-DD] | [Name] | [Initial release: codifies ADR-NNNN] |
id: STD-NNNN # claimed from the standards folder; never guess the next number title: "[Short, imperative title, e.g. Server Hardening Baseline]" status: draft # draft | in-review | active | superseded | retired version: 1.0 owner: "[Named person accountable for currency: a person, not a team]" review_team: "[Security, affected platform teams, compliance where applicable]" author: "[Name, role]" source_adrs: [] # REQUIRED: the accepted ADRs that justify this standard supersedes: none superseded_by: none compliance_mappings: [] # e.g. PCI DSS, NIST 800-53, CIS, your regional regulators review_cadence: annual # minimum, plus the out-of-cycle triggers in §07 next_review: YYYY-MM-DD last_updated: YYYY-MM-DD ai_assistance: none
<!-- For AI assistants. This is a Standard: the living rulebook answering "what are the rules today?". Versioned, owned, reviewed on cadence, machine-verified where possible. Rules: exactly one capitalized RFC 2119 keyword per control. Complete each control row: requirement, mapping, verification, evidence. If a control can't be tied to a source ADR, flag the gap and suggest an RFC: write no unjustified rules. Keep procedures out; they belong in a runbook. Ground truth: fill a field only from what the human told you or gave you; otherwise keep the [placeholder] and ask. Ask: Which accepted ADRs justify these controls? How is each control verified by machine, and where do results land? Which compliance frameworks must the mapping cover? -->
STD-NNNN: [Short, imperative title]
The living rulebook. ADRs hold the why; this holds the what. One standard, one control domain.
The justification test. Every standard cites the accepted ADRs that produced it. If no ADR can justify a rule, question whether the rule should exist. A standard with no source ADRs does not pass review.
01 · Purpose and scope
[The risk or inconsistency this standard removes, and the position the organization takes.]
| Boundary | Definition |
|---|---|
| In scope | [Systems, environments, accounts, e.g. "all production server instances"] |
| Out of scope | [Exclusions, and the standard that covers them] |
02 · Roles and responsibilities
| Role | Responsibility |
|---|---|
| Standard owner | Keeps it current, runs the review cycle, owns the exception register |
| Review team | Validates operational feasibility and compliance alignment at each review |
| Enforcing teams | Implement and operate the controls |
| All engineers | Comply with MUST controls; request an exception when they can't |
03 · Requirement language (RFC 2119)
Every control uses exactly one of these, capitalized.
| Keyword | Meaning |
|---|---|
| MUST / SHALL | Absolute requirement. Non-compliance needs an approved, time-boxed exception (§05) |
| MUST NOT | Absolute prohibition. Same exception process |
| SHOULD | Strong recommendation. Deviation needs a documented justification |
| MAY | Genuinely optional, once every MUST and SHOULD is met |
04 · Controls
Number controls STD-NNNN-CC and group them by function. This section says what must be true, not how: procedures belong in a linked runbook, so the rules stay stable while the procedures evolve.
[Control group A, e.g. Authentication and access]
| ID | Requirement | Mapping | Verification | Evidence |
|---|---|---|---|---|
| STD-NNNN-01 | [All administrative sessions MUST enforce MFA] | [NIST IA-2; PCI DSS 8.4] | [Query sign-in logs for admin roles] | [Exported policy; sign-in log sample] |
| STD-NNNN-02 | [Data at rest SHOULD be encrypted with AES-256] | [NIST SC-28] | [Config rule / volume encryption query] | [Generated config report; key rotation logs] |
[Control group B, e.g. Logging and monitoring]
| ID | Requirement | Mapping | Verification | Evidence |
|---|---|---|---|---|
| STD-NNNN-11 | [...] | [...] | [...] | [...] |
05 · Exceptions
A controlled, time-boxed deviation with explicit risk acceptance. Indefinite waivers quietly accumulate risk debt.
- Every exception MUST be time-boxed: 12 months maximum, shorter where the remediation plan allows.
- Every exception MUST name a risk owner with the authority to accept the risk. Approving one is accepting a risk, not granting a bypass.
- Every exception MUST define compensating controls and a remediation plan.
- 90 days before expiry, the submitter is asked for a status update; renewal runs an abbreviated approval.
- An exception that lapses without review is a governance failure, and is escalated as one.
- Approval scales with blast radius: one team → standard owner; cross-team or compliance-relevant → architecture forum; enterprise or regulatory exposure → CISO or executive risk owner.
Compensating controls must meet the intent and rigor of the original requirement, defend against the same risk, go beyond what other controls already require, and cover the extra risk of the deviation for its full duration. "We accept the risk" is not a compensating control.
| ID | Scope | Risk owner | Compensating controls | Approved by | Expires | Status |
|---|---|---|---|---|---|---|
| EX-01 | [Systems / controls excepted] | [Name, role] | [Mitigations in place] | [Name] | [YYYY-MM-DD] | [Active / Expired / Closed] |
06 · Verification and drift detection
Check adherence continuously, not only at review time. Prefer policy-as-code and scheduled scans over manual attestation.
| Aspect | Definition |
|---|---|
| Method | [e.g. config rules, compliance policies, scheduled benchmark scans] |
| Cadence | [Continuous / daily / weekly, per control group] |
| Results land in | [Dashboard / SIEM / compliance report] |
| Drift response | [Auto-remediate / ticket / escalate, by criticality] |
07 · Review and maintenance
Reviewed at least annually, plus out of cycle when triggered by:
- A major architectural change in the control domain
- A new or changed regulatory requirement
- Relevant threat intelligence
- A newly accepted ADR that supersedes or amends a source ADR
| Version | Date | Author | Change |
|---|---|---|---|
| 1.0 | [YYYY-MM-DD] | [Name] | [Initial release: codifies ADR-NNNN] |
Runbook (RUN)
---
id: RUN-NNNN
title: "[Task-oriented title]"
type: incident-response # incident-response | how-to | scheduled-operation | onboarding
status: published # published | archived
owner: "[Named person accountable for accuracy]"
author: "[Name, role]"
implements_stds: [] # standards whose rules this procedure implements, or none
systems_touched: []
required_access: [] # verify these before you need them at 3 a.m.
last_tested: YYYY-MM-DD # by whom; stale if blank or old
last_updated: YYYY-MM-DD
ai_assistance: none
---
<!--
For AI assistants. This is a Runbook: a step-by-step operational procedure answering
"how do I do it?". Non-normative: the rules it implements live in standards.
Rules: give every state-changing step a Verify cell with the concrete expected output.
Write commands copy-paste ready, with placeholders clearly marked. For a step with no
rollback path, write "no rollback: escalate before executing". State stop conditions
explicitly: halting beats momentum in an incident.
Ground truth: fill a field only from what the human told you or gave you; otherwise keep the
[placeholder] and ask.
Ask: What exactly triggers this procedure? What access does the executor need, and what is
the escalation path without it? When was it last tested, and by whom?
-->
# RUN: [Task-oriented title]
How to do one thing, step by step, with verification and rollback. Rules live in standards, reasoning in ADRs.
> **Test it like a fire extinguisher.** An outdated runbook is more dangerous than none. Update Last Tested every time it's exercised, in anger or in a game day. A runbook nobody has tested in a year belongs in the archive, not in your trust.
## 01 · When to use this
| Aspect | Detail |
|---|---|
| Triggers | [Alert name / error pattern / threshold / scheduled task] |
| Impact if untreated | [User-visible impact and severity] |
| Who executes | [Role: on-call SRE, DBA, platform engineer] |
## 02 · Prerequisites
Everything needed before step 1. Link consoles, dashboards and log queries directly: hunting for links mid-incident is how mistakes happen.
- [Permission or role required, and the escalation path if you lack it]
- [Tooling: CLI versions, network access path, bastion or session access]
- [Observability links: dashboard, log query, trace view, alert definition]
- [Variables: name, where the value comes from, an example]
## 03 · Procedure
Every step that changes state carries its own verification. Capture evidence as you go: UTC timestamp, executor, approver, before and after state.
| # | Action | Verify before continuing |
|---|---|---|
| 1 | [Exact command or console action, copy-paste ready] | [Expected output or state] |
| 2 | [...] | [...] |
| 3 | [...] | [...] |
> **Stop conditions.** [Signals that mean halt and roll back: a validation error, unexpected blast radius, error rate climbing after a step. Pushing past one turns an incident into an outage.]
## 04 · Rollback
Treat the procedure as a transaction: undo in reverse order to last known-good.
| Step | Compensating action |
|---|---|
| 3 | [How to undo step 3] |
| 2 | [How to undo step 2] |
| 1 | [How to undo step 1, or "no rollback: escalate before executing"] |
## 05 · Escalation
| Escalate to | When | How |
|---|---|---|
| [SME / owning team] | [e.g. restore fails, or lag stays above 60 s after two checks] | [Chat channel / on-call schedule] |
| [Incident commander] | [User-visible impact ongoing] | [Paging path] |
## 06 · Maintenance
Log every exercise, including dry runs. Archive, don't delete, when this stops earning its keep.
| Date | Exercised by | Context | Changes made |
|---|---|---|---|
| [YYYY-MM-DD] | [Name] | [Incident ID / game day] | [e.g. steps 2–3 updated: new console path] |
id: RUN-NNNN title: "[Task-oriented title]" type: incident-response # incident-response | how-to | scheduled-operation | onboarding status: published # published | archived owner: "[Named person accountable for accuracy]" author: "[Name, role]" implements_stds: [] # standards whose rules this procedure implements, or none systems_touched: [] required_access: [] # verify these before you need them at 3 a.m. last_tested: YYYY-MM-DD # by whom; stale if blank or old last_updated: YYYY-MM-DD ai_assistance: none
<!-- For AI assistants. This is a Runbook: a step-by-step operational procedure answering "how do I do it?". Non-normative: the rules it implements live in standards. Rules: give every state-changing step a Verify cell with the concrete expected output. Write commands copy-paste ready, with placeholders clearly marked. For a step with no rollback path, write "no rollback: escalate before executing". State stop conditions explicitly: halting beats momentum in an incident. Ground truth: fill a field only from what the human told you or gave you; otherwise keep the [placeholder] and ask. Ask: What exactly triggers this procedure? What access does the executor need, and what is the escalation path without it? When was it last tested, and by whom? -->
RUN: [Task-oriented title]
How to do one thing, step by step, with verification and rollback. Rules live in standards, reasoning in ADRs.
Test it like a fire extinguisher. An outdated runbook is more dangerous than none. Update Last Tested every time it's exercised, in anger or in a game day. A runbook nobody has tested in a year belongs in the archive, not in your trust.
01 · When to use this
| Aspect | Detail |
|---|---|
| Triggers | [Alert name / error pattern / threshold / scheduled task] |
| Impact if untreated | [User-visible impact and severity] |
| Who executes | [Role: on-call SRE, DBA, platform engineer] |
02 · Prerequisites
Everything needed before step 1. Link consoles, dashboards and log queries directly: hunting for links mid-incident is how mistakes happen.
- [Permission or role required, and the escalation path if you lack it]
- [Tooling: CLI versions, network access path, bastion or session access]
- [Observability links: dashboard, log query, trace view, alert definition]
- [Variables: name, where the value comes from, an example]
03 · Procedure
Every step that changes state carries its own verification. Capture evidence as you go: UTC timestamp, executor, approver, before and after state.
| # | Action | Verify before continuing |
|---|---|---|
| 1 | [Exact command or console action, copy-paste ready] | [Expected output or state] |
| 2 | [...] | [...] |
| 3 | [...] | [...] |
Stop conditions. [Signals that mean halt and roll back: a validation error, unexpected blast radius, error rate climbing after a step. Pushing past one turns an incident into an outage.]
04 · Rollback
Treat the procedure as a transaction: undo in reverse order to last known-good.
| Step | Compensating action |
|---|---|
| 3 | [How to undo step 3] |
| 2 | [How to undo step 2] |
| 1 | [How to undo step 1, or "no rollback: escalate before executing"] |
05 · Escalation
| Escalate to | When | How |
|---|---|---|
| [SME / owning team] | [e.g. restore fails, or lag stays above 60 s after two checks] | [Chat channel / on-call schedule] |
| [Incident commander] | [User-visible impact ongoing] | [Paging path] |
06 · Maintenance
Log every exercise, including dry runs. Archive, don't delete, when this stops earning its keep.
| Date | Exercised by | Context | Changes made |
|---|---|---|---|
| [YYYY-MM-DD] | [Name] | [Incident ID / game day] | [e.g. steps 2–3 updated: new console path] |
Statement of work (SOW)
---
id: SOW-NNNN
title: "[Project name]"
status: draft # draft | in-review | approved
version: 0.1
owning_team: "[Team name]"
author: "[Name, role]"
sponsor: "[Executive sponsor, title]"
parent_sad: "" # the SAD this delivers against, or "standalone"
related_adrs: [] # decisions this SOW implements or is constrained by
last_updated: YYYY-MM-DD
ai_assistance: none
---
<!--
For AI assistants. This is a Statement of Work: a bounded delivery document answering
"what are we delivering?". It has a start and an end, and is frozen at done.
Rules: pair every deliverable with a verifiable acceptance criterion. Treat the Minimum
Viable Solution as a floor to defend: push scope out of it, not in. When a significant
architectural decision surfaces, send it to an RFC and record only the resulting ADR link
here. Ask for the parent SAD and related ADR IDs early.
Ground truth: fill a field only from what the human told you or gave you; otherwise keep the
[placeholder] and ask.
Ask: What is explicitly out of scope? What are the floors for scale, uptime, testability and
observability? Which SAD capability does this SOW deliver?
-->
# SOW: [Project name]
A bounded delivery document: what gets delivered, and it's frozen at done.
## 01 · Description
[What the project is and why it exists.]
## 02 · Documentation
- [Doc link or note]
## 03 · Objectives
- [Objective]
## 04 · Scope of work
Define the boundaries early, and list what's explicitly out of scope.
[What the project includes, and where relevant what it doesn't.]
| Source | Target | Notes |
|---|---|---|
| [System / DB / path] | [System / DB / path] | [Caveats; for migrations only] |
## 05 · Minimum viable solution
The smallest version that meets the primary purpose, with explicit non-functional floors. If it's not in the MVS, it's deferred.
- **Scalability:** [Handle [current load] and scale to [anticipated load]]
- **Reliability:** [Achieve [uptime goal] with failover to [fallback]]
- **Testability:** [Tests cover [critical functions]]
- **Observability:** [Logging for [key operations], monitoring on [primary metrics]]
## 06 · Deliverables
| Deliverable | Acceptance criterion |
|---|---|
| [Deliverable] | [How we'll know it's done] |
## 07 · Resources
- [Team: people involved]
## 08 · Implementation
[Before/after flowcharts, architecture diagrams.]
> **Big decision mid-flight?** It doesn't get buried in this SOW. Raise an RFC, take it through the forum, and link the resulting ADR in the frontmatter. This document records delivery, not decisions.
### Critical path
What must work reliably for the system to operate: what, not how.
| Step | Action | SLO |
|---|---|---|
| 1 | [Action or milestone] | [Respond within [X] ms for [P]% of requests] |
| 2 | [Following action] | [Complete within [Y] s for [Q]% of users] |
## 09 · Dependencies (optional)
- **External:** [Team or resource needed to complete [task]]
- **Internal:** [Team or system dependency]
## 10 · Assumptions (optional)
- [Assumption]
## 11 · Risks (optional)
- [Risk]
## 12 · Basis for time estimate (optional)
| Item | Rough estimate |
|---|---|
| [Milestone 1] | [Estimate] |
| [Milestone 2] | [Estimate] |
| Total | [Estimate] |
## 13 · Purposeful design checklist
- **Aligned with business need:** [Focuses on [core objective] without [unneeded features]]
- **No premature optimization:** [Optimizes [current bottleneck], not speculative future needs]
- **MVS is complete:** [Includes [necessary components] without [extra complexity]]
> **Scope is a contract.** Any change to scope, timeline or deliverables after approval goes through formal change management.
## 14 · References
- [Document or resource name and link]id: SOW-NNNN title: "[Project name]" status: draft # draft | in-review | approved version: 0.1 owning_team: "[Team name]" author: "[Name, role]" sponsor: "[Executive sponsor, title]" parent_sad: "" # the SAD this delivers against, or "standalone" related_adrs: [] # decisions this SOW implements or is constrained by last_updated: YYYY-MM-DD ai_assistance: none
<!-- For AI assistants. This is a Statement of Work: a bounded delivery document answering "what are we delivering?". It has a start and an end, and is frozen at done. Rules: pair every deliverable with a verifiable acceptance criterion. Treat the Minimum Viable Solution as a floor to defend: push scope out of it, not in. When a significant architectural decision surfaces, send it to an RFC and record only the resulting ADR link here. Ask for the parent SAD and related ADR IDs early. Ground truth: fill a field only from what the human told you or gave you; otherwise keep the [placeholder] and ask. Ask: What is explicitly out of scope? What are the floors for scale, uptime, testability and observability? Which SAD capability does this SOW deliver? -->
SOW: [Project name]
A bounded delivery document: what gets delivered, and it's frozen at done.
01 · Description
[What the project is and why it exists.]
02 · Documentation
- [Doc link or note]
03 · Objectives
- [Objective]
04 · Scope of work
Define the boundaries early, and list what's explicitly out of scope.
[What the project includes, and where relevant what it doesn't.]
| Source | Target | Notes |
|---|---|---|
| [System / DB / path] | [System / DB / path] | [Caveats; for migrations only] |
05 · Minimum viable solution
The smallest version that meets the primary purpose, with explicit non-functional floors. If it's not in the MVS, it's deferred.
- Scalability: [Handle [current load] and scale to [anticipated load]]
- Reliability: [Achieve [uptime goal] with failover to [fallback]]
- Testability: [Tests cover [critical functions]]
- Observability: [Logging for [key operations], monitoring on [primary metrics]]
06 · Deliverables
| Deliverable | Acceptance criterion |
|---|---|
| [Deliverable] | [How we'll know it's done] |
07 · Resources
- [Team: people involved]
08 · Implementation
[Before/after flowcharts, architecture diagrams.]
Big decision mid-flight? It doesn't get buried in this SOW. Raise an RFC, take it through the forum, and link the resulting ADR in the frontmatter. This document records delivery, not decisions.
Critical path
What must work reliably for the system to operate: what, not how.
| Step | Action | SLO |
|---|---|---|
| 1 | [Action or milestone] | [Respond within [X] ms for [P]% of requests] |
| 2 | [Following action] | [Complete within [Y] s for [Q]% of users] |
09 · Dependencies (optional)
- External: [Team or resource needed to complete [task]]
- Internal: [Team or system dependency]
10 · Assumptions (optional)
- [Assumption]
11 · Risks (optional)
- [Risk]
12 · Basis for time estimate (optional)
| Item | Rough estimate |
|---|---|
| [Milestone 1] | [Estimate] |
| [Milestone 2] | [Estimate] |
| Total | [Estimate] |
13 · Purposeful design checklist
- Aligned with business need: [Focuses on [core objective] without [unneeded features]]
- No premature optimization: [Optimizes [current bottleneck], not speculative future needs]
- MVS is complete: [Includes [necessary components] without [extra complexity]]
Scope is a contract. Any change to scope, timeline or deliverables after approval goes through formal change management.
14 · References
- [Document or resource name and link]
Opportunity brief (BRIEF)
---
id: BRIEF-NNNN
title: "[Outcome-phrased opportunity title]"
status: draft # draft | pitched | funded | parked
author: "[Name, role]"
sponsor_sought: "[Executive whose backing this needs]"
resulting: "" # the SAD / SOW, filled when funded
date: YYYY-MM-DD
ai_assistance: none
---
<!--
For AI assistants. This is an Opportunity Brief: a one-page executive pitch answering
"why fund this?". Its only job is to win sponsorship; the architecture comes later, in
the SAD it spawns.
Rules: business language throughout (cost, time, risk, competitive position); no jargon.
Every number the human hasn't supplied is a question, not an estimate. Express the
investment as a range and state the exact decision needed. Over one page? Cut until it fits.
Ground truth: fill a field only from what the human told you or gave you; otherwise keep the
[placeholder] and ask.
Ask: What does inaction cost, quantified? What specific approval is being requested? Which
numbers, by which dates, measure success?
-->
# BRIEF: [Outcome-phrased opportunity title]
> **One page when filled.** Bottom line up front, outcomes not technology. Aim for a third text, a third visual, a third white space. If it spills past a page, it's a SAD trying to be born: cut until it fits.
## 01 · The problem
What keeps leadership up at night, in cost, time, risk or competitive position.
[Current situation: the market shift, bottleneck, regulatory pressure or contract event forcing the question.]
[Cost of doing nothing: money, time, risk, quantified.]
## 02 · Options
Validated options, not a single path. The recommendation goes first and says why it wins.
| Option | What it is | Why / why not |
|---|---|---|
| [Recommended] | [One line] | [Why it delivers the best value] |
| [Alternative B] | [One line] | [Why bypassed: cost, risk, time] |
| Status quo | Do nothing | [What that costs: ties to §01] |
## 03 · The ask
Use a range, not a point estimate: ranges survive first contact with finance.
| Element | Detail |
|---|---|
| Decision needed | [The approval requested, and by when] |
| Investment | [$X–$Y: licence, effort, run cost] |
| Timeline | [Phase 1 value by, full delivery by] |
| Owner if funded | [Who runs it, and the SAD / SOW that gets spun up] |
## 04 · Success measures
Numbers with dates, so the follow-up conversation is about results, not recollections.
| Measure | Target | By when |
|---|---|---|
| [ROI / payback / cost reduction] | [$ or %] | [Quarter] |
| [Operational metric, e.g. cycle time] | [From X to Y] | [Quarter] |
| [Adoption, e.g. teams onboarded] | [N of M] | [Quarter] |
id: BRIEF-NNNN title: "[Outcome-phrased opportunity title]" status: draft # draft | pitched | funded | parked author: "[Name, role]" sponsor_sought: "[Executive whose backing this needs]" resulting: "" # the SAD / SOW, filled when funded date: YYYY-MM-DD ai_assistance: none
<!-- For AI assistants. This is an Opportunity Brief: a one-page executive pitch answering "why fund this?". Its only job is to win sponsorship; the architecture comes later, in the SAD it spawns. Rules: business language throughout (cost, time, risk, competitive position); no jargon. Every number the human hasn't supplied is a question, not an estimate. Express the investment as a range and state the exact decision needed. Over one page? Cut until it fits. Ground truth: fill a field only from what the human told you or gave you; otherwise keep the [placeholder] and ask. Ask: What does inaction cost, quantified? What specific approval is being requested? Which numbers, by which dates, measure success? -->
BRIEF: [Outcome-phrased opportunity title]
One page when filled. Bottom line up front, outcomes not technology. Aim for a third text, a third visual, a third white space. If it spills past a page, it's a SAD trying to be born: cut until it fits.
01 · The problem
What keeps leadership up at night, in cost, time, risk or competitive position.
[Current situation: the market shift, bottleneck, regulatory pressure or contract event forcing the question.]
[Cost of doing nothing: money, time, risk, quantified.]
02 · Options
Validated options, not a single path. The recommendation goes first and says why it wins.
| Option | What it is | Why / why not |
|---|---|---|
| [Recommended] | [One line] | [Why it delivers the best value] |
| [Alternative B] | [One line] | [Why bypassed: cost, risk, time] |
| Status quo | Do nothing | [What that costs: ties to §01] |
03 · The ask
Use a range, not a point estimate: ranges survive first contact with finance.
| Element | Detail |
|---|---|
| Decision needed | [The approval requested, and by when] |
| Investment | [$X–$Y: licence, effort, run cost] |
| Timeline | [Phase 1 value by, full delivery by] |
| Owner if funded | [Who runs it, and the SAD / SOW that gets spun up] |
04 · Success measures
Numbers with dates, so the follow-up conversation is about results, not recollections.
| Measure | Target | By when |
|---|---|---|
| [ROI / payback / cost reduction] | [$ or %] | [Quarter] |
| [Operational metric, e.g. cycle time] | [From X to Y] | [Quarter] |
| [Adoption, e.g. teams onboarded] | [N of M] | [Quarter] |
The review request
A pull request tells you that work exists (a branch, a diff, some green checks). It tells you nothing about whether a human was asked for anything. You can open a PR, keep pushing to it, and leave it open all week because you want CI to run, and none of that is a request for review.
An objection I hear a lot is that tracking review state somewhere else is duplicate work. Cool, but check the assumption first: an open PR and work that's ready for another human look like the same event and aren't the same fact. Move the item to Review and the state becomes the message. The author moves the card to ask, and nothing is blocked if they don't, so a state you set in order to ask has no reason to be faked. What that buys you: a timestamp, a count of how many times the work bounced back, and the name of whoever looked (which is more than a chat ping leaves behind).
Your request is the signal, and the artifact is only the evidence attached to it. If you want advice, say advice. If you want a decision, say decision. Say it in the first line, because a reader who has to guess what you want will pick the cheaper option, which is nothing.
Document access
One rule ended a lot of argument for me: no artifact counts unless a reader outside the team can open it. A decision parked in a private channel, in a personal drive folder, or behind a sharing dialog doesn't exist in any useful sense. Of the first 20 pre-reads that reached our intake, the one place a request comes in, 8 lived in somebody's personal drive folder and 1 existed nowhere I could reach at all. A personal link 403s for everyone else, so every reference to it in your decision log is a dead end. If the one person who can open it leaves, you never had the document.
The flip side of openness is a readership decision: the moment a file that was shared with three named people lands in our company-readable library, I've granted everyone access to it. That's why copies come in through a check of their own (content, sharing, findable, not already there), and why money and live security detail come out of a document before it moves. Ask who can read it before you move it.
Template location
Standards came later as a fourth type, once enough decisions pointed the same way, and I had prefixed it STD, which reads as an unrelated acronym to anyone outside a standards conversation. A display-only change would've left two names for one document type, which is exactly the drift the framework exists to stop, so we did the full rename while exactly one document used it, an afternoon's work at the time.
Then I got the bill for where our templates lived. The chain ran one way:
Edit a copy at the far end and the next sync wipes it. A hard-coded file name for the old type stayed inside the tool, so the old name outlived the rename, and a document with the old name turned up on another site long after everyone agreed the rename was finished. A search of one site proves only that one site is clean.
The version I'd start with today: one template, where the work happens, in the repo your engineers already have open. If a copy has to exist somewhere else, know which copy is upstream and edit that one, then check the whole estate before you call a rename done.
Field freezes
Freezing fields is where architecture functions overreach (mine included). One blunt test: does anything downstream use the value, not just check that it's there? If a rollup, a report, a search or an audit depends on that field, freeze it and tell people why (a frozen field with a stated reason is easier to live with). If nothing uses it, leave it free.
My judgement, and only a judgement: the freeze question is the best filter I've found for telling governance that helps a team from governance that performs for an audience.
Ours passes that test in one place. Every item in an architecture area carries one link to its portfolio row, because the weekly rollup counts rows for people outside the architecture function, so that link is frozen and the field carries help text saying why. The approval date that opened this post failed the same test: the gate checked that a value was there, and nothing used it.
A freeze protects a value that already exists. It doesn't stop that value being cleared, and it does nothing at all to a field nobody has filled in yet. So protect a field in every state (before it's valid, while it's required, after it's recorded), and test it live.
What you can do this week
None of this needs permission. Three things you can do without asking anyone:
- Put the templates next to the work: start with the three we started with (decision record, design doc, request for comments), or take all seven.
- Take something you're about to do, write the request, and send it to two people it affects. Say in the first line whether you want advice or a decision.
- Pick a decision your team already made, write it as a decision record, and put it somewhere a reader outside your team can open.
All seven templates are above, each ready to copy.
That's a working architecture language on day one: the seven questions, the place to ask, and one record you can defend.
Next up, the forum: where a request lands, and what has to leave the room for it to count.
VP of Enterprise Architecture at a consumer finance company. 15+ years shipping systems that handle real money.
Connect on LinkedIn