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:

---
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:

**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.