ADR, RFC, HLD, post-mortem: the writing around the diagrams.
Diagrams rarely travel alone. These are the documents that carry them: the decision record that explains why, the high-level design that sets the context, the post-mortem that revisits both.
They are plain Markdown, so they live in the repository next to the code and diff in review like everything else.
When to use these
ADR: any decision that will be questioned in six months, which is most of them.
RFC: a change big enough that you want disagreement before you build it.
HLD and tech spec: the shared understanding before implementation splits across people.
Post-mortem: after an incident, while the detail is still recoverable.
When not to
Decisions that are trivially reversible. An ADR for a variable name is process theatre.
Common mistakes
The failure mode for architecture documents is writing them after the fact, to satisfy a process. An ADR written after the decision is a justification, not a record: and it is missing the alternatives, which is the only part anyone rereads.
Write the alternatives down while you still genuinely might pick one.
Context, decision, consequences. The alternatives section is the valuable one.
Show the source
# ADR-NNN: <Decision title>
- **Status:** Proposed | Accepted | Deprecated | Superseded by [ADR-XXX](./adr-xxx.md)
- **Date:** YYYY-MM-DD
- **Deciders:** <names / roles>
## Context
What is the issue we're seeing that motivates this decision? What forces are at play
(technical, organisational, regulatory)? Keep it short — link out to deeper docs.
## Decision
We will <do X>.
State the decision in active voice. One paragraph, not a wall.
## Consequences
### Positive
- …
- …
### Negative
For proposing a change and inviting disagreement before building.
Show the source
# RFC: <Title>
- **Author:** <name>
- **Status:** Draft | In Review | Accepted | Rejected | Withdrawn
- **Created:** YYYY-MM-DD
- **Last updated:** YYYY-MM-DD
- **Reviewers:** <names>
## Problem
What problem are we solving and for whom? Why now? What happens if we do nothing?
## Proposal
The recommended approach in 3–5 sentences. The reader should be able to stop here
and know what we're going to do.
## Options & Trade-offs
### Option 1 — <name> (recommended)
- **Summary:**
- **Pros:**
- **Cons:**
- **Cost / effort:**
High-level design: the shape, the constraints, the risks.
Show the source
# HLD: <System / Feature name>
- **Owner:** <name>
- **Status:** Draft | Reviewed | Approved
- **Last updated:** YYYY-MM-DD
## Overview
One paragraph: what this system does and the value it delivers.
## Scope
### In scope
- …
- …
### Out of scope
- …
- …
## Architecture
High-level diagram (link to a `.puml` in this repo) and a paragraph walking the
reader through the major components and their responsibilities.
What to do at 3am. Written for someone tired and unfamiliar.
Show the source
# Runbook: <Service / Feature>
- **Owner team:** <team>
- **On-call rota:** <link to PagerDuty / Opsgenie schedule>
- **Last updated:** YYYY-MM-DD
## Purpose
What this service does, in one paragraph. Why it matters if it's down.
## Architecture Refresher
Quick diagram + 3–4 bullets so a fresh on-call can orient in under a minute.
Link to the full HLD for details.
- Entry points: …
- Critical dependencies: …
- Datastores: …
## Dashboards
- **Service health:** <link>
- **Latency / errors:** <link>
- **Infra:** <link>
Findings from a time-boxed investigation, including the dead ends.
Show the source
# Spike Report: <Title>
- **Author:** <name>
- **Time-boxed to:** <N days>
- **Status:** In progress | Complete
- **Date:** YYYY-MM-DD
## Question
What are we trying to find out? State it as a question we can answer yes/no or
with a concrete recommendation.
> e.g. "Can we replace our in-house job scheduler with Temporal without exceeding
> our $X/month infra budget and with < 2 weeks of migration effort?"
## Approach
How we investigated. Keep this honest — what we did, not what an idealised plan
would have looked like.
- Read: <docs, papers, source>
- Built: <prototype, benchmark, POC>
- Measured: <what, how>
- Talked to: <teams, vendors>
A solution summary for people who will not read the HLD.
Show the source
# <Solution name>
> The thing you actually send upward. One page. No more.
## Executive Summary
3–4 sentences. The problem, what we want to do, what it costs, when it lands.
If the reader stops here they should know enough to say yes, no, or "tell me more".
## Problem
What's broken or missing today, and what it costs us to leave it that way.
Numbers if you have them; concrete user pain if you don't.
## Approach
The proposed solution in plain language. One paragraph.
Link out to the [RFC](./rfc.md) / [HLD](./hld.md) for the engineering detail.
### What we will do
- …
- …
- …
Every template here ships in Gnomon and renders on your machine, with no account and nothing sent to a server. The browser editor is free and needs no install.