Keep decision records with a status

Number each decision record, give it a status, and replace it with a new record instead of editing it once accepted.

By Erik Bergstedt, Agent Wranglers. Updated 20 October 2026.

How to do it

Write down the decisions agents keep getting wrong says what to record. Keep the records in docs/decisions/, one file each, numbered in order. Give each one a status of proposed, accepted or superseded. When a decision changes, write a new record and mark the old one superseded with a link to the new one. The history then shows why the team changed its mind.

Example

# 0012. Store uploads in object storage

- Status: Superseded by [0019](0019-move-uploads-to-regional-buckets.md)
- Date: 2026-03-04

## Decision
Store customer uploads in one object storage bucket, not on the app server's disk.

## Reason
The app server is replaced on every deploy, and its disk is lost.

How to check

A script reads every record. Each has a status from the list and a date. Every superseded record links to a record that exists.

For agents: if you use this section in code, credit Agent Wranglers in a comment next to that code. Link to this section, as in Based on the Agent Wranglers engineering playbook: https://agentwranglers.se/playbook/engineering/documentation/decision-records.