vaultspec-adr git:20260924.2797685A

Immutable. This exact content never changes and is served at /api/v1/blob/ad90ae49d6e3d37a.

---
name: vaultspec-adr
description: Record a new or changed costly decision after checking accepted decision coverage and sufficient Research, Reference, or Audit evidence.
---

# ADR (vaultspec-adr)

Records one costly decision. Apply the coverage and approval contract in the vaultspec
system section before creating a record. Reuse an accepted ADR unchanged when it covers
the work, including across features; return its stem without drafting a duplicate.

## Steps

- Check coverage per the `vaultspec-discovery` rule: search for the decision, then list
  the ADRs across features. No covering record in the listing, together with a "nothing
  in the vault answers this" (`nothing_answers`) verdict, shows the decision is new.
  When search gives no such verdict (it declined or failed, or replied "no record that
  was read answers this", `none_read_answers`), the ADR listing plus a targeted grep of
  `.vault/adr/` decide coverage. That is the rule's `.vault/` grep, narrowed to
  decisions. Read covering decisions whole, then their evidence. Classify the need as
  unchanged reuse, amendment, supersession, or a distinct decision.
- Confirm sufficient Research, Reference, or Audit evidence. Gather missing evidence
  through `vaultspec-research` for option research or `vaultspec-code-research` for code
  patterns. Do not copy an adequate Audit into a new Research merely for its type.
- For a new decision, scaffold:
  `vaultspec-core vault add adr --feature {feature} --related <evidence-stem>` (or
  `create`). Read `.vaultspec/templates/adr.md`.
- Draft the decision, or dispatch `vaultspec-adr-researcher` with the existing evidence
  and requested decision scope; it returns content for persistence.
- Once the decision sections are persisted, cross-reference the ADR with `crossref`
  (CLI: `vaultspec-core vault adr crossref <adr-stem>`). This step is optional and
  recommended. Read each `link` verdict's ADR and add the ones you confirm to `related:`
  with `vaultspec-core vault link add`. Read in full every pair labelled `supersedes`,
  `refines`, or `conflicts` before you settle amendment, supersession, or a distinct
  decision. The label marks a pair to read; it never decides. When the reply is
  `not_configured` or `unavailable`, run the next step it names instead.
- For an amendment, preserve accepted content while proposing the revision separately.
  Follow the system's pending-proposal procedure if it must survive handoff.
- For a reversal, draft the successor first. After its content is authorized, set it
  `accepted`, then run `vaultspec-core vault adr supersede OLD --by NEW`.
- Verify with `vaultspec-core vault check all`. Present the record and authorization
  basis. If authorization is missing, ask and stop. Otherwise persist acceptance and
  continue with the authorized work. Rejected proposals remain as evidence; rejection
  never changes the accepted predecessor.

## Document boundary

Evidence stays in Research, Reference, or Audit. Cite it by stem; add missing facts to
their evidence home before using them. The ADR owns the decision, rationale, and
consequences. Decision language found in evidence moves here only when authorized.