Decision record template in Markdown: log why, not just what

A decision record template gives you one plain Markdown file per choice. The file says what was picked, why, and which options were turned down, so the reasoning is still there when someone opens the folder months from now. That someone could be you, a coworker, or any reader who was not there for the discussion.

This post gives you a template to copy, a short note on each field, and a filled-in sample. Any text editor you already have will do. There is nothing to install.

What a decision record is

A decision record is a short .md file about one choice. It names the problem, lists the options that were in play, says which one won, and spells out what follows from it. Once the choice is made, the file stays as a record of why, long after the work it shaped is done. A folder of them becomes a decision log in Markdown that you can search later.

This post uses decision record and ADR, short for architecture decision record, for the same kind of file. MADR is one public Markdown format for decision records. The template below is this post's own.

A handoff file does a different job. It reports to the next session how far the work got and what to do now, and it changes as the work moves along. For the parts of a handoff and a quick way to read one, see the agent handoff file guide. A decision record answers a narrower question that stays fixed: why this option and why the others lost.

The decision record template

Copy this block into a new .md file and swap the placeholder text for your own. Labeled lines sit at the top, and the longer fields get their own headings, so you can fill it in with any plain editor.

# 0000: Short name of the choice

Status: proposed
Date: YYYY-MM-DD
Supersedes: none
Superseded by: none

## Context

What is going on, and why a choice is needed now.
Two to five sentences a stranger could follow.

## Options considered

- Option A: one line on what it is. Lost: the reason.
- Option B: one line on what it is. Lost: the reason.
- Option C: one line on what it is. Chosen.

## Decision

The option picked, in one sentence, plus the main reason.

## Consequences

- What gets easier because of this choice.
- What gets harder, or what it costs.
- What would make you open the question again.

## Follow-ups

- The next action, and who owns it.

What each field is for:

• Title. The heading holds a number and a few words naming the choice. Write it as the thing decided, such as "Folder layout for agent notes".
• Status. This template uses three values: proposed, accepted and superseded. A record starts as proposed and moves to accepted once the choice is made.
• Date. The day the status last changed, written as YYYY-MM-DD.
• Supersedes and Superseded by. The number of an older or newer record on the same question, or none. These two lines let a reader follow a chain of choices in either direction.
• Context. The situation and the reason a choice was needed. Write it for a reader who missed every conversation about it.
• Options considered. One list item per option, with a short reason it lost or the word Chosen. This is the field that keeps the rejected paths on record.
• Decision. One sentence that names the option picked and the main reason.
• Consequences. The gains and the costs that come with the choice, plus the signal that would reopen it.
• Follow-ups. Actions the choice creates, each with an owner. When they are done, the record still stands.

A filled-in sample

Here is the template filled in. Doe Holdings and Jane Doe are made up, and this is a sample with no real project behind it.

# 0003: Folder layout for agent notes

Status: accepted
Date: 2026-10-12
Supersedes: none
Superseded by: none

## Context

Doe Holdings keeps notes for three jobs in one shared folder.
Jane Doe can't tell which notes belong to which job, and plans
from finished jobs sit next to current ones.

## Options considered

- One flat folder with dated file names. Lost: jobs still mix together.
- One running log file for all notes. Lost: one huge file to re-read.
- One folder per job, with a handoff file in each. Chosen.

## Decision

Use one folder per job, named with the start date and a short topic,
because it keeps each job's notes in one place.

## Consequences

- Jane Doe can point a new session at a single folder.
- Someone has to move finished job folders out of the active list.
- Revisit if a single job needs more than one agent at a time.

## Follow-ups

- Jane Doe moves the current notes into job folders by Friday.

Each rejected option carries its reason on its own line. A reader who later wonders why Doe Holdings skipped a single running log finds the answer in the file, without asking anyone.

Where the files go and what to call them

This post's choice is a decisions/ folder with one numbered file per decision, such as decisions/0003-agent-notes-layout.md. The number gives each record a short id that other files can cite, as in "see decision 0003". Keeping one decision per file keeps each record small, and lets a newer record replace an older one without editing a shared file.

A decision can outlive the job that raised it, so this post keeps the folder at the root of your docs, beside the job folders. For the rest of that layout, the guide on organizing agent-written docs sets out a system of job folders, handoff files, an index and a folder for finished jobs. For the words after the number, Markdown file naming conventions goes through case, hyphens, the .md ending and why a name should stay put once links point at it.

Writing a record for later readers

A reader who comes back to it later has only the file to go on. Some habits help a record make sense months after the choice:

• Write the context for a stranger. Spell out names, numbers and the problem itself. A phrase like "the thing from that call" means nothing to someone who missed the call.
• Give each rejected option a reason. "Too slow to review" is short and still useful. A bare list of names leaves the next reader guessing.
• Keep a replaced record. When a choice changes, write a new record, set the old one to superseded, and fill in the Supersedes and Superseded by lines on both. Deleting the old file throws away the reasons behind the first choice.
• Say what would reopen it. A line in Consequences such as "Revisit if two jobs start sharing files" tells a later reader when the question is live again.

If you like, ask your own agent to read the decisions/ folder, or to append a new record when you settle something in a session. Read any new record against the template, the same way you'd read one of your own.

For the wider habit of preparing files to give your own agent, the guide to Markdown task files covers task files, a header block and a file skeleton to copy.

When something went wrong and got fixed, write it up in a postmortem, a separate file with its own timeline and action items.

The short decisions and tasks from one meeting go in meeting minutes, a file of their own.

Where Sashmark fits

On the drawing board, Sashmark is desktop software that would let you read Markdown and edit it too, meant for those whose AI agents keep writing .md files. The app is in development right now, and no build of it is out yet. A folder where you keep decision records is the kind of file set its plan has in mind.

See the planned features, the help pages and the roadmap for where each part stands.

Visit sashmark.com.