decision-record
Writes down a decision in the place this project already keeps decisions. Use the project's own
format, never a second one.
Why the project's format, not a good one. A decision written in a format nobody reads gets lost.
Examples: an OpenSpec change in a repo whose decisions live in docs/adr/, or a new docs/decisions/
beside an existing log. So detection comes first. Where the record goes is settled by evidence in
the tree, not by preference.
When a decision needs a record
Record it when the change:
- adds a feature or a capability callers can see
- changes behaviour, a contract, a data format or a default that someone relies on
- adds or removes a dependency, a tool or a supported platform
- reverses or narrows an earlier recorded decision (supersede it — do not edit it)
Skip it for a bug fix that restores intended behaviour, a refactor with no behaviour change,
docs, formatting or a version bump. When unsure, write the record. A short record costs less
than re-litigating the decision later.
Step 1 — Detect
python3 .ai-badger/skills/decision-record/scripts/detect_formats.py . --json
The script reports:
mode: adr, spec, combination or none
- each ADR log:
dir, tool, naming (sequence or date), count, the next number
(null for a date-named log), the newest record and the index file
- each spec framework:
openspec, spec-kit or kiro, with the folder that marked it
- which CLIs are on PATH:
openspec, specify, adr, log4brains
warnings: a marker it could not read, or one that points outside the project. Report each
warning to the person. Never write to a path a warning names.
The list of recognised markers lives in the script. Read it there; do not restate it.
An installed CLI is not adoption. A CLI decides how to write into a format the tree already
shows. It never decides which format. Do not run openspec init, specify init or adr init,
and do not install anything. If a tool would help a project that has none, say so in the record's
consequences and leave the choice to the people who own the repo.
Step 2 — Write, by mode
adr — an ADR log exists
- More than one log (a monorepo, or a log4brains config with package folders): write to the
log that owns the code being changed. That is the one whose folder shares the longest path
with it. Use the root log for a cross-cutting decision.
- Sequence-named: before you take the
next number, fetch and check it against
origin/<default-branch>. A concurrent PR may have taken it. Date-named (next is null):
name the file with today's date in the log's own date form (20261023- or 2026-10-23-).
- Copy the shape of the
newest record: headings, status line, metadata block, date format, and
how it cites superseded records. The log's own convention beats any template.
- With
tool: adr-tools and adr on PATH, create the file with adr new <title>
(adr new -s <N> <title> to supersede), then fill it in. With tool: log4brains and
log4brains on PATH, use log4brains adr new. Otherwise write the file by hand as
<next or date>-<kebab-title>.md.
- If the log has an
index, add the row in that index's format in the same change.
spec — a spec framework exists
- OpenSpec. Prefix every call with
OPENSPEC_TELEMETRY=0. Run openspec list --specs to reuse an existing
capability path, then openspec new change <kebab-name>. For each artifact, get the template
from the CLI instead of writing it from memory:
openspec instructions <proposal|specs|design|tasks> --change <kebab-name>. The decision itself
goes in design.md: the options considered, the one chosen and why, and the consequences.
Finish with openspec validate <kebab-name> and fix whatever it refuses. A change with no
requirement delta sets skip_specs: true in its .openspec.yaml. If openspec/ exists but
the CLI does not, mirror an existing change folder by hand and state that it went unvalidated.
- Spec Kit (reported by its
.specify/ state folder). Write in the feature's specs/<NNN-slug>/, not in .specify/. Requirements go in spec.md and the decision
in plan.md (or research.md when the folder has one). Use the /speckit-* commands if the host exposes them.
- Kiro. Write in
.kiro/specs/<slug>/. Requirements go in requirements.md and the decision in design.md.
combination — both exist
Write both, and keep each half in one place:
- the spec change states what the system must do: requirements, scenarios, tasks
- the ADR states why: the context, the options, the choice, the consequences
Link them both ways: the ADR names the spec change's path, and the spec's design artifact
names the ADR. Do not copy the rationale into both. Two copies drift, and then nobody knows which
one is true.
none — nothing detected
Only when detection found nothing, write a MADR 4 minimal record at the reported fallback
(docs/decisions/0001-<kebab-title>.md) from references/madr-minimal.md. That is MADR's
documented default location, and plain Markdown needs no tool.
Step 3 — Content and status
- Write the record before implementation, with the status the log uses for an open decision
(
Proposed in MADR). Move it to Accepted in the PR that implements it.
- Name at least two considered options, including doing nothing. A record with one option is an
announcement, not a decision.
- State how compliance will be confirmed: a test, a gate, or a review question.
- Logs that never edit an accepted record (this repo's
docs/adr/ is one) change only by a new
record that supersedes the old one. Name the supersession in both.
Gotchas
- A CLI on PATH with no project artifacts is a machine-wide install, not adoption (
openspec was
installed globally on the machine this skill was written on, and the repo had never run
openspec init).
- OpenSpec collects usage telemetry by default. Set
OPENSPEC_TELEMETRY=0.
- Two open PRs that each take
next collide on merge. Check the number against the default branch just
before you commit.
Verification checklist
Files
scripts/detect_formats.py — tree and PATH detection; --json for the full result.
references/madr-minimal.md — read only when mode is none: the fallback template.
1---2name: decision-record-23description: >-4 Use when a change adds a feature or meaningfully changes how something works and the decision5 behind it has to be written down before implementation — "record this decision", "write an6 ADR", "open a spec change", "decision record", or the task skill's decision-record step.7 Detects what the project already uses (an ADR log in MADR, adr-tools or log4brains shape;8 OpenSpec, Spec Kit or Kiro specs; the CLIs on PATH), writes into that format, and writes a9 linked ADR-plus-spec pair when the project keeps both.10version: 1.0.011author: ai-badger12license: MIT13platforms: [linux, macos, windows]14scope: default15metadata:16 source: https://skillmd.com/skills/arasz/decision-record-217 hermes:18 tags: [adr, decisions, specification, openspec, documentation]19 related_skills: [task, create-task-spec, evidence-first-research]20---2122# decision-record2324Writes down a decision in the place this project already keeps decisions. Use the project's own25format, never a second one.2627**Why the project's format, not a good one.** A decision written in a format nobody reads gets lost.28Examples: an OpenSpec change in a repo whose decisions live in `docs/adr/`, or a new `docs/decisions/`29beside an existing log. So detection comes first. Where the record goes is settled by evidence in30the tree, not by preference.3132## When a decision needs a record3334Record it when the change:3536- adds a feature or a capability callers can see37- changes behaviour, a contract, a data format or a default that someone relies on38- adds or removes a dependency, a tool or a supported platform39- reverses or narrows an earlier recorded decision (supersede it — do not edit it)4041Skip it for a bug fix that restores intended behaviour, a refactor with no behaviour change,42docs, formatting or a version bump. When unsure, write the record. A short record costs less43than re-litigating the decision later.4445## Step 1 — Detect4647```bash48python3 .ai-badger/skills/decision-record/scripts/detect_formats.py . --json49```5051The script reports:5253- `mode`: `adr`, `spec`, `combination` or `none`54- each ADR log: `dir`, `tool`, `naming` (`sequence` or `date`), `count`, the `next` number55 (`null` for a date-named log), the `newest` record and the `index` file56- each spec framework: `openspec`, `spec-kit` or `kiro`, with the folder that marked it57- which CLIs are on PATH: `openspec`, `specify`, `adr`, `log4brains`58- `warnings`: a marker it could not read, or one that points outside the project. Report each59 warning to the person. Never write to a path a warning names.6061The list of recognised markers lives in the script. Read it there; do not restate it.6263**An installed CLI is not adoption.** A CLI decides *how* to write into a format the tree already64shows. It never decides *which* format. Do not run `openspec init`, `specify init` or `adr init`,65and do not install anything. If a tool would help a project that has none, say so in the record's66consequences and leave the choice to the people who own the repo.6768## Step 2 — Write, by mode6970### `adr` — an ADR log exists71721. **More than one log** (a monorepo, or a log4brains config with package folders): write to the73 log that owns the code being changed. That is the one whose folder shares the longest path74 with it. Use the root log for a cross-cutting decision.752. **Sequence-named:** before you take the `next` number, fetch and check it against76 `origin/<default-branch>`. A concurrent PR may have taken it. **Date-named** (`next` is `null`):77 name the file with today's date in the log's own date form (`20261023-` or `2026-10-23-`).783. Copy the shape of the `newest` record: headings, status line, metadata block, date format, and79 how it cites superseded records. The log's own convention beats any template.804. With `tool: adr-tools` and `adr` on PATH, create the file with `adr new <title>`81 (`adr new -s <N> <title>` to supersede), then fill it in. With `tool: log4brains` and82 `log4brains` on PATH, use `log4brains adr new`. Otherwise write the file by hand as83 `<next or date>-<kebab-title>.md`.845. If the log has an `index`, add the row in that index's format in the same change.8586### `spec` — a spec framework exists8788- **OpenSpec.** Prefix every call with `OPENSPEC_TELEMETRY=0`. Run `openspec list --specs` to reuse an existing89 capability path, then `openspec new change <kebab-name>`. For each artifact, get the template90 from the CLI instead of writing it from memory:91 `openspec instructions <proposal|specs|design|tasks> --change <kebab-name>`. The decision itself92 goes in `design.md`: the options considered, the one chosen and why, and the consequences.93 Finish with `openspec validate <kebab-name>` and fix whatever it refuses. A change with no94 requirement delta sets `skip_specs: true` in its `.openspec.yaml`. If `openspec/` exists but95 the CLI does not, mirror an existing change folder by hand and state that it went unvalidated.96- **Spec Kit** (reported by its `.specify/` state folder). Write in the feature's `specs/<NNN-slug>/`, not in `.specify/`. Requirements go in `spec.md` and the decision97 in `plan.md` (or `research.md` when the folder has one). Use the `/speckit-*` commands if the host exposes them.98- **Kiro.** Write in `.kiro/specs/<slug>/`. Requirements go in `requirements.md` and the decision in `design.md`.99100### `combination` — both exist101102Write both, and keep each half in one place:103104- the **spec change** states *what* the system must do: requirements, scenarios, tasks105- the **ADR** states *why*: the context, the options, the choice, the consequences106107Link them both ways: the ADR names the spec change's path, and the spec's design artifact108names the ADR. Do not copy the rationale into both. Two copies drift, and then nobody knows which109one is true.110111### `none` — nothing detected112113Only when detection found nothing, write a MADR 4 minimal record at the reported `fallback`114(`docs/decisions/0001-<kebab-title>.md`) from `references/madr-minimal.md`. That is MADR's115documented default location, and plain Markdown needs no tool.116117## Step 3 — Content and status118119- Write the record **before implementation**, with the status the log uses for an open decision120 (`Proposed` in MADR). Move it to `Accepted` in the PR that implements it.121- Name at least two considered options, including doing nothing. A record with one option is an122 announcement, not a decision.123- State how compliance will be confirmed: a test, a gate, or a review question.124- Logs that never edit an accepted record (this repo's `docs/adr/` is one) change only by a new125 record that supersedes the old one. Name the supersession in both.126127## Gotchas128129- A CLI on PATH with no project artifacts is a machine-wide install, not adoption (`openspec` was130 installed globally on the machine this skill was written on, and the repo had never run131 `openspec init`).132- OpenSpec collects usage telemetry by default. Set `OPENSPEC_TELEMETRY=0`.133- Two open PRs that each take `next` collide on merge. Check the number against the default branch just134 before you commit.135136## Verification checklist137138- [ ] `detect_formats.py` ran, and the record went where its `mode` says139- [ ] An existing log's newest record was the shape template, not this skill's fallback140- [ ] The index row exists if the log has an index141- [ ] `openspec validate` passed for an OpenSpec change, or the record says it was not validated142- [ ] In `combination` mode, the ADR and the spec change link to each other and the rationale lives only in the ADR143- [ ] At least two options are considered, and the confirmation method is named144- [ ] No framework was initialised and no tool installed145146## Files147148- `scripts/detect_formats.py` — tree and PATH detection; `--json` for the full result.149- `references/madr-minimal.md` — read only when `mode` is `none`: the fallback template.