--- name: decision-records description: Creates, supersedes and validates decision records (ADRs) against the convention a collection already follows, instead of imposing a published one. Use when the user wants to record a decision, write an ADR, supersede an existing decision, audit or lint a decisions folder, check that an ADR index is in sync, or asks "why did we decide X". Deduces the filename scheme, section set and status vocabulary from the records already there; ships a validator with an exit code, so the audit is a check and not an opinion. argument-hint: "[new | supersede | check []]" allowed-tools: Bash(ls:*), Bash(find:*), Bash(cat:*), Bash(grep:*), Bash(bash:*), Read, Write, Edit --- # 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" ``` 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. ## 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 `, 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`, `-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* | | `DRIFT` | one status spelled two ways: `Accepted` beside `accepted` | | `SUPERSEDE` | a reference that resolves to nothing, or a status claiming supersession that names no replacement | | `DUPLICATE` | two records claiming one identifier, where the scheme carries one (`NNNN-slug.md`, `ADR-031-slug.md`); under a dated or free-form scheme the whole filename is the identifier and cannot collide | | `INDEX` | the index and the directory disagreeing, **in either direction** | | `PORTABLE` | with `--portable`: absolute paths, and links that climb out of the collection | Three deliberate properties: - **A check that cannot apply says so.** Every run ends with *checks that did not run* on stderr, naming each check and why. Without it a reader sees `OK: no violations` and has no way to know how many of the eight were in a position to say anything, and silence reads as a pass. Two shipped defects came from exactly that gap. - **Nothing is imposed.** The required sections are the ones most records already have, the filename scheme is the one most records already use. `--require` and `--status` are there for a collection that wants to be held to something stricter than its current habits, and they are the only way a rule enters that the collection is not already following. - **An empty directory exits 2, not 0.** A clean verdict over zero records reads as "clean" to anyone checking the exit code, which is how a guard stops guarding while staying installed. ## A declared limit: a status is assumed to be a token The `STATUS` and `DRIFT` checks assume the status field holds a **word**, and key the deduced vocabulary off its first word. Some collections put a paragraph there instead: a status word followed by two sentences of narrative and a list of cross-references. On those, the deduced vocabulary is the first word of prose and means nothing, and `--status` would report every such record as outside the vocabulary. That is a limit, not a bug to normalise away: deciding where a token ends inside free text is guesswork, and guessing is how a validator starts reporting a collection's own convention back to it. Do not pass `--status` on a collection whose status field carries prose. Everything else on it still works, because the other seven checks do not read that field. When the user asks "why did we decide X", read the index first, then the matching records, and answer from Context and Decision. If nothing matches, say so and offer to record one. ## Auditing a collection for private tokens Not this skill's job, and not duplicated here. If `privacy-guard` is set up in the repo, its denylist is the list: ```sh grep -n -i -E -f <(grep -vE '^[[:space:]]*(#|$)' .local/privacy-denylist.txt) /*.md ``` `check_privacy.sh` itself reads `git diff --cached`, so it covers a record on its way into a commit but not one already sitting in the tree. Its own skill names that limit and says to grep the tracked tree against the denylist by hand for an audit; the line above is one way to do that, written here rather than there. ## Important rules - **ALWAYS** run the validator and read its convention report before writing a record. - **ALWAYS** get explicit approval before writing a record to disk, and write nothing when the user declines. - **ALWAYS** update the index in the same turn as the record. - **NEVER** create a `template.md` in the target repo. - **NEVER** edit an accepted record to change the decision; supersede it. - **NEVER** reuse an identifier, including one freed by deleting a record. - **NEVER** report a collection as clean on an exit code you did not look at: the validator exits 2 when it had nothing to check, and 2 is not 0.