decision-records · git:20260913.a6ef6f5 · 2026-09-13 · sha256 c9bd6f7678a95c5b
decision-records git:20260913.a6ef6f5B
Immutable. This exact content never changes and is served at /api/v1/blob/c9bd6f7678a95c5b.
No tool to install first
claude plugin marketplace add https://markdownregistry.com/mp/a/art_bko2vaczsde6dnde/c9bd6f7678a95c5b16b0500bcb6029c9136dbc333e9c2766d1dee47e07cb916a.json
Then /plugin install decision-records@markdownregistry-bko2vaczsde6dnde in Claude Code. It installs this exact version, the one graded B here, pinned to the commit it was graded at, and leaves it there.
--- name: decision-records description: Write or update decision and implementation-plan records in a repository's records directory (usually `docs/records/`, also known as ADRs, decision logs, or design docs). Use for architecture, product, design, privacy, security, dependency, delivery, or other durable project decisions. Use when creating a record, changing a record's status, writing an amendment, superseding a record, updating the record registry, or bootstrapping a records directory in a repo that has none. --- # Project records A records directory is a repository's durable registry for decisions and implementation plans. A record explains what the team decided, why, and what follows from that decision. Records are historical evidence: they are appended to and amended, not rewritten. Do not use a record for a routine code change, a temporary task, a release note, or an investigation without a durable outcome. ## Find the records directory 1. Look for an existing registry, in this order: `docs/records/`, `docs/adr/`, `docs/decisions/`, `adr/`, `decisions/`, or any directory that contains a `README.md` with a table of numbered records. Check the project's `README.md`, `CONTRIBUTING.md`, `AGENTS.md`, or `CLAUDE.md` for a pointer. 2. If a registry exists, its `README.md` is the contract. It is the authority for ID format, filename pattern, frontmatter, status vocabulary, and required headings. Follow it even where it differs from the defaults below. 3. If no registry exists, ask the user whether to create one. If they agree, create `docs/records/README.md` from the template in "Bootstrap a registry" before writing the first record. ## Read first 1. Read the registry `README.md` completely. 2. Read the records that relate to the work. 3. Read the product, design, or architecture source that defines the facts. 4. If a record conflicts with newer evidence, preserve the record's history and record the correction or new decision. Do not edit the old text in place. Do not copy a legacy record's errors into a new record. When a legacy record and the registry contract disagree, the contract wins. ## Create a record Create a record only after the decision or plan has a clear scope. Ask for missing product or technical facts before you invent them. 1. Find the next unused ID in the registry table. Default format is a global three-digit number (`001`, `002`, ...). Never reuse or skip an ID. 2. Name the file `<id>-<short-kebab-case-title>.md`. 3. Add the exact frontmatter contract from the registry README. Keep every list key, even when the list is empty. 4. Use `kind: decision` for a durable choice. Use `kind: plan` for committed, outcome-based work. 5. New decisions start as `proposed` until accepted. New plans start as `planned` until work begins. Use another valid status only when the current state differs. 6. Set `date` and `updated` to the creation date. Use ISO dates (`YYYY-MM-DD`). 7. Start with the six required headings, in this order: - `## Intent` - `## Context` - `## Record` - `## Consequences` - `## Validation / Current state` - `## Related records` 8. Add the new row to the registry table in the README. The table row is part of the change. Keep its ID, title, kind, status, date, supersession, and related-record fields aligned with the record's frontmatter. ### Default frontmatter Use this when the registry README does not define its own: ```yaml --- id: 007 title: Short title kind: decision # decision | plan status: proposed # see "Status rules" date: 2026-09-13 updated: 2026-09-13 supersedes: [] superseded_by: [] related: [] --- ``` ## Write the sections Write factual, direct prose in plain English. Use the project's own terms, matching the related records. Prefer short sentences and concrete nouns over abstractions. If the repo has a writing-style skill or guide, apply it. ### Intent State the user or project outcome. State what the record makes possible or protects. Do not repeat implementation detail here. ### Context State the facts, constraints, research, risks, and alternatives that shaped the choice. Link evidence (issues, PRs, benchmarks, docs) when it is useful. Mark assumptions and open questions as such. ### Record State the decision or plan precisely. Use numbered items when the contract has several rules. Name scope boundaries and required behavior. For a plan, make the desired outcome and completion evidence clear. ### Consequences State costs, tradeoffs, follow-up work, and intentionally deferred work. Do not present a consequence as a requirement unless the record commits to it. ### Validation / Current state State the current, observable status. For completed work, name the evidence: tests, checks, measurements, or human acceptance. For proposed or active work, state what remains. Do not claim that work shipped or passed unless the evidence exists. ### Related records Use this form: ```md **Supersedes:** None. **Related:** - [005 — Short title of record 005](005-short-title.md) ``` Use relative links. Keep the frontmatter ID lists in the same order as the links in this section. ## Update a record A record is historical evidence. Preserve its ID, filename, creation date, and past decisions. - Change `updated` only for a substantive content change. - Change `status` only to a value valid for the record kind. - Add a dated `## Amendment (YYYY-MM-DD) — <short title>` for a later decision, correction, or material scope change. Put it after the existing material. - Update `## Validation / Current state` when new evidence changes the status. - Create a new record when a decision or plan is fully replaced. Put the old IDs in the new record's `supersedes`, set the old record's status to `superseded` and its `superseded_by`, and update the registry rows. - Use `related`, not `supersedes`, for a dependency, coordinated work, or a partial refinement. - Never silently rewrite history to make an old decision look current. A superseded record stays in the registry. Do not renumber, delete, or reuse its ID. ## Status rules Default vocabulary, unless the registry README defines its own: - Decisions: `proposed`, `accepted`, `superseded`, `rejected`. - Plans: `planned`, `active`, `completed`, `blocked`, `superseded`, `rejected`. A status tells the truth about the record. It does not predict the desired outcome. ## Bootstrap a registry Only when the user agrees to create one. Write `docs/records/README.md` with: 1. A one-paragraph statement of what belongs in a record and what does not. 2. The ID and filename pattern. 3. The frontmatter contract (copy the default above). 4. The status vocabulary per kind. 5. The six required headings in order. 6. An empty registry table with these columns: `ID | Title | Kind | Status | Date | Supersedes | Related`. Keep the README short. It is a contract, not a guide. ## Final review Before you finish: 1. Make sure that the new ID is unique and matches the filename. 2. Make sure that the frontmatter has every required key and valid values. 3. Make sure that the required headings exist in the required order. 4. Make sure that every linked or listed record ID exists. 5. Make sure that `supersedes` means full replacement. 6. Make sure that the registry row and frontmatter agree. 7. Read the record as a future maintainer. Remove vague promises and unsupported claims. 8. Run `git diff --check`. If the repo has a Markdown linter or link checker, run it on the changed files. Do not run the app build or test suite for a records-only change.