---
title: "Keep decision records with a status · Agent Wranglers"
url: https://agentwranglers.se/playbook/engineering/documentation/decision-records
updated: 2026-10-20
licence: "All rights reserved"
---

# Keep decision records with a status

By Erik Bergstedt, Agent Wranglers. Updated 2026-10-20.

- Level: Recommended
- Chapter: [Documentation](https://agentwranglers.se/playbook/engineering/documentation)
- Rule: Number each decision record, give it a status, and replace it with a new record instead of editing it once accepted.
- How: [Write down the decisions agents keep getting wrong](https://agentwranglers.se/playbook/ai-assisted-development/setting-up-the-project/record-decisions) 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.
- 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.

Example:

```markdown
# 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.
```

**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`.

- Previous: [Change the docs in the same pull request](https://agentwranglers.se/playbook/engineering/documentation/docs-with-the-change)
- Next: [Keep runbooks next to the code they run](https://agentwranglers.se/playbook/engineering/documentation/runbooks-in-repo)
- [Documentation](https://agentwranglers.se/playbook/engineering/documentation)