Engineering: Templates
Four working templates: the architecture decision record, the change checklist, the irreversible-change authorisation and the gate audit.
Markdown. No sign-up, no email.
Four documents. Each exists because of a question asked after something went wrong: why was it built this way, what was checked before it shipped, who authorised the thing that could not be undone, and which gate should have caught it.
1. Architecture decision record#
One per decision that changes a contract, a data shape, or how two systems talk.
| Field | Entry |
|---|---|
| Decision | [State it as a question with more than one real answer] |
| Date and decider | [A name. Decisions do not have committees] |
| Context | [What forced the question now] |
| Options considered | [At least two. One option is not a decision] |
| Rejected, and why | [The most valuable row here. It is what stops the debate recurring, and what tells a future reader this was considered rather than defaulted] |
| Chosen | |
| Consequences accepted | [What this makes harder. Every choice makes something harder] |
| Reversible? | [If not, it also needs the authorisation below] |
| Revisit when | [A condition, not a date. "If write volume passes 10x" beats "in a year"] |
2. Change checklist#
Per change, whatever its size. Small changes cause most incidents because they skip steps.
| Check | Done |
|---|---|
| One purpose. Nothing unrelated in the branch | ⬜ |
| Tests written in the same pass as the code | ⬜ |
| AI review clean, or findings answered individually | ⬜ |
| Human review, if it touches a contract, auth, money or data | ⬜ |
| Suite green. No skipped tests | ⬜ |
| Security scan clean, or a risk accepted with a name and date | ⬜ |
| Documentation updated from the diff | ⬜ |
| Rollback path known | ⬜ |
| Named accepter | ⬜ |
A skipped test is a failing test with better manners. If it is skipped, say why in the pull request or delete it.
3. Irreversible change authorisation#
For a schema migration, a data deletion, a public API contract, or anything touching money.
| Field | Entry |
|---|---|
| Change | |
| Why it cannot be undone | [Be concrete. "Difficult" is not "impossible"] |
| Rollback path | [Written and tested, not described] |
| Backup taken and restore verified | [A backup nobody has restored is a hope] |
| Blast radius if wrong | [Who and what is affected, in numbers] |
| Window | [When, and who is watching] |
| Authorised by | [A named human, separate from the code reviewer] |
| Date |
No agent executes this, whatever its confidence. Confidence is not the qualifying condition; recoverability is.
4. Gate audit#
Monthly, thirty minutes, one row per gate.
| Gate | Fired | Bypassed | False positives | Caught something no later gate would | Action |
|---|---|---|---|---|---|
| AI code review | |||||
| Automated tests | |||||
| Security scan | |||||
| CI/CD checks | |||||
| Human acceptance |
| Question | Answer |
|---|---|
| Any gate at zero this month? | [Investigate. Either misconfigured, or being routed around] |
| Any bypass without a written reason? | [A process failure regardless of the outcome] |
| Anything reach production that a gate should have stopped? | [Name the gate and fix it, not the person] |
Using these together#
The charter sets out the delivery model, the SOPs say when each template is produced, the KPIs define what the gate audit feeds, and the workflows name who receives each output. A decision record written without the SOP that governs it is a tidy document that changed nothing.