agent-skills/skills/maintain-decision-records/SKILL.md

name, description

name	description
maintain-decision-records	Use when creating, accepting, evolving, superseding, rejecting, auditing, or archiving durable engineering decision records while preserving rationale, alternatives, consequences, accurate lifecycle status, and valid links.

Maintain Decision Records

A decision record preserves why a durable choice exists and what it gave up. Code and current docs own present mechanics; the record owns decision rationale, alternatives, consequences, and conditions that prevent re-litigation.

1. Find the owner before creating a record

Search existing active and rejected records by concept, affected interface, and alternative. Update the existing owner when the decision is unchanged. Do not create one record per PR or duplicate the same rationale under a new title.

Create a record when a change alters behavior, architecture, a shared contract, process, testing strategy, durable/wire/config format, security boundary, or another choice a maintainer may reasonably revisit. Skip purely mechanical local edits.

Use a stable path convention if the project has none:

decisions/<status>/YYYY-MM-DD-<short-topic>.md

Use relative Markdown links between records so moves can be checked mechanically.

2. Choose the truthful lifecycle

• proposed: decision is under review or only partly implemented;
• accepted: decision is current and shipped;
• rejected: proposal was considered and declined;
• superseded: a newer decision replaces all or part of it;
• archived: frozen historical snapshot with low current decision value.

Status is truth, not workflow aspiration. Never leave “accepted” on an unshipped proposal. Never edit an accepted record into the opposite decision.

3. Write the appropriate skeleton

Proposed:

# Decision: <title>

Status: proposed

## Problem
## Proposal
## Alternatives considered
## Acceptance criteria
## Risks

Accepted:

# Decision: <title>

Status: accepted

## Problem
## Decision
## Alternatives considered
## Consequences
## Verification

Rejected:

# Decision: <title>

Status: rejected — <one-line verdict>

## Problem
## Proposal
## Alternatives considered
## Rejection rationale

Every record starts with the problem independently of its preferred solution. Record genuine alternatives and why each lost; do not invent straw alternatives after the fact.

4. Move a proposal to accepted

In the same change that ships it:

1. move/update status to accepted;
2. rewrite future-tense Proposal as present-tense Decision;
3. replace plans with what actually shipped;
4. convert acceptance criteria into evidence under Verification;
5. fold realized risks and trade-offs into Consequences;
6. update paths, symbols, defaults, formats, and links;
7. preserve alternatives and rationale.

An accepted record must describe shipped reality, not its implementation checklist.

5. Keep current facts accurate without rewriting history

When the same decision moves files, renames symbols, or changes a realization detail, update those facts in the accepted record. Do not append a chronological changelog.

When the decision or rationale reverses, create a new record. Add reciprocal links:

Status: superseded by [Use append-only events](../accepted/2026-08-15-append-only-events.md)

The new record explains what it supersedes and why. For partial supersession, keep both active and state which scope each owns.

Delete a fully superseded record only when the current owner preserves every unique rationale, alternative, consequence, verification obligation, and named gap, and every inbound link is repaired. Git history is not the only acceptable copy.

6. Handle rejected records deliberately

Keep a rejected record only when the losing idea remains tempting and its rationale prevents a meaningful mistake. Freeze the proposal and make the verdict prominent. Delete it when the premise is obsolete, the idea is no longer plausible, or a newer record fully owns the warning. Repair inbound links when deleting.

Do not relabel a rejected proposal as accepted by rewriting it in place; create or revive the correct decision history explicitly.

7. Distinguish four storage roles

• Active rationale: accepted record whose trade-offs, ownership boundary, negative guarantee, or reintroduction condition still guides work. Keep current.
• Current-state decision: concise accepted record that owns a live rule even if implementation detail lives elsewhere. Keep current.
• Rejected fallacy prevention: rejected record that blocks a plausible bad choice. Keep readable but stable.
• Frozen archive: low-future-value implemented history retained for provenance, not current authority. Freeze it.

Age and word count do not decide archival. Archive only accepted records whose rationale is unlikely to guide future changes. Never archive a proposal; reject it or continue review.

8. Archive safely

Before archiving:

1. confirm current docs/code own the present behavior;
2. inspect inbound links;
3. redirect active guidance to current authority;
4. move the record to the archive without modernizing its body;
5. add only archive metadata required by the repository;
6. freeze it against future edits.

Active prose may cite an archived record as intentional history, but not as current operational authority. Do not repair outbound links inside a sealed archive if the project treats archives as frozen.

9. Mechanical audit

Check:

• path lifecycle agrees with Status;
• required headings match lifecycle;
• accepted decisions use present tense;
• proposed-only plans are absent from accepted records;
• alternatives exist and are real;
• consequences include both benefits and costs;
• supersession links are reciprocal and resolve;
• every relative link resolves after moves;
• no duplicate active owner exists;
• archive files are unchanged except the authorized archival move/metadata.

Report records created, updated, accepted, superseded, rejected, deleted, archived, and deliberately kept, including borderline calls and their governing rationale.