decision-records

Files (2)

• SKILL.md
• check-decisions.sh · scripts/

SKILL.md (first lines)

# decision-records

Decision records are cheap to write and expensive to trust. The expensive part is the
collection: numbers that collide, an index that stopped matching the directory, a record
that says it was superseded and does not say by what. This skill writes records and,
mainly, **holds a collection to its own convention**.

## What this skill does not do

- **It does not ship a template file into the target repo.** The skeleton is in this file.
  A `template.md` next to the records is a second home for the convention, and two homes
  diverge in silence: the template keeps a section the records dropped a year ago and
  nothing says which one is the convention. The most-installed prior art
  (`affaan-m/ECC`, `skills/architecture-decision-records`) creates one; this is a
  deliberate departure, not an oversight.
- **It does not check for private tokens.** Hostnames, instance names, IP ranges and
  personal identity belong to the `privacy-guard` skill, whose denylist is gitignored on
  purpose. Duplicating that list here would put the same list in two places, which is the
  failure above with worse consequences. The `--portable` check covers only what breaks
  when a record is **copied**: absolute paths, and links that climb out of the collection.
- **It does not rewrite an accepted record to change its mind.** See *Superseding*.

## Step 0, always: read the collection before writing anything

Find the collection. The three defaults in the wild are all different, so look, do not
assume: `doc/adr` (adr-tools), `docs/adr` (the ECC skill), `docs/decisions` (MADR 4.0.0).

```sh
bash "${CLAUDE_PLUGIN_ROOT}/skills/decision-records/scripts/check-decisions.sh" <dir>
```

Its first block reports what the collection does: filename scheme, where the status lives,
the status vocabulary in use, the sections most records carry, and the index. **That report
is the convention.** Everything you write next matches it, including the parts you would
have written differently.

If the collection is empty or does not exist, ask once, and offer both schemes:

| Scheme | Gains | Costs |
|---|---|---|
| `NNNN-slug.md` **(recommend this one)** | a short reference you can say out loud: "see 0007" | two parallel PRs both take the next number and both merge ([adr/madr#28](https://github.com/adr/madr/issues/28), open since 2020, no convention adopted); breaks on copy between repos and on reordering |
| `YYYY-MM-DD-slug.md` | no collision between parallel PRs, survives a copy into another repo, sorts correctly | no short reference: you cite a record by its whole filename |

Recommend the numbered scheme unless the repo takes decisions through parallel PRs, which
is the case the date scheme was invented for (`log4brains` adopted it in that thread for
exactly this reason). Nothing else about the record changes with the choice.

## Creating a record

1. **Draft, do not write.** Compose the record and show it in the conversation.
2. **Wait for explicit approval.** "Looks good", "yes, write it". Silence is not approval.
   If the user declines, discard it: write nothing, leave no file behind.
3. **Write** it to the collection, named for the deduced scheme, numbered `max + 1` when the
   scheme is numbered (never reuse a number, not even of a deleted record).
4. **Update the index** in the same turn, if the collection keeps one. A record written and
   not indexed is the defect the `INDEX` check exists to catch; do not create it and then
   report it.
5. **Re-run the validator.** It is the only thing that tells you the write landed inside the
   convention rather than beside it.

The skeleton, for a collection that has none to deduce. Sections adapt to the collection's
own set when there is one:

```markdown
# NNNN. <decision in a short noun phrase>

## Status

proposed

## Context

What forced a decision now. The constraints, the pressure, what was true at the time.
Not the solution.

## Decision

What we do, in the present tense: "We use X". One or two sentences.

## Consequences

What gets easier, what gets harder, what we now owe. Both directions, honestly: a record
with only benefits documents an advert, not a decision.
```

Two rules about content, from Nygard's original and worth keeping: write **why**, because
the what is already visible in the code; and record the alternative that was rejected and
the reason, because the next person will otherwise re-propose it.

## Superseding

An accepted record is a statement about a moment. **Never edit one to change its mind** —
that destroys the only evidence of why the old decision made sense, and the record's whole
value is that evidence.

1. Write a new record (the flow above), whose Status references the old one.
2. Change the **old** record's status to `superseded by <new ref>`, and nothing else in it.
3. Update the index for both.

Use the reference form the collection already uses. The validator resolves markdown links
(`[0009](0009-slug.md)`), `ADR-0009`, and a bare number, and reports one that resolves to
nothing. A bare number is only resolvable where the filename scheme carries one; under a
dated or free-form scheme records cite each other by filename, and the validator says it
left those references unchecked rather than calling them all dangling.

## Validating

```sh
check-decisions.sh [--require "A,B"] [--status "a,b"] [--portable] DIR
# 0 clean, 1 violations, 2 usage error or nothing to check
```

Eight checks, each printing a stable code so the reason is readable and greppable:

| Code | What it catches |
|---|---|
| `NAME` | a filename outside the scheme the other records use, or a collection that agrees on no scheme at all. Four schemes are recognised: `YYYY-MM-DD-slug.md`, `NNNN-slug.md`, `<prefix>-NNN-slug.md`, and free-form |
| `SECTION` | a section missing from a record that more than half the collection carries |
| `STATUS` | a record with no status, in a collection whose other records have one. Four forms are read: frontmatter `status:`, a `- Status:` bullet, `**Status**:`, a `## Status` section. When **no** record has one, that is not eight violations, it is one line in *checks that did not run* |

From fvadicamo/dev-agent-skills, MIT.

More from fvadicamo/dev-agent-skills