adr-supersedelisted
Install: claude install-skill real-case/marvin-toolkit
# ADR Supersede
Retire a decision **the right way**: not by editing or deleting the old record, but by pairing
it with a successor. The old record's history stays byte-identical except for its header —
status flips to `superseded` with a link to the successor; the successor carries the
`Supersedes` link back. This is a human gate of the ADR lifecycle (ADR-0027): the user runs it
deliberately.
The pairing mechanics live in the **`adr` MCP tool** — its `supersede` action validates
fail-closed and performs the two-sided link flip atomically per file. Never hand-edit statuses
or supersede links.
## Input
`$ARGUMENTS` — the record being superseded (number or title fragment), optionally with the
replacement: a new title, or the number of an existing record to pair as successor.
## Workflow
### 1. Identify the old record
- Call the `adr` MCP tool with `{"action": "list"}`; resolve `$ARGUMENTS` (number first, then
title). With no argument, ask which decision is being rolled back.
- Confirm the pick with the user when it came from a fragment — a supersession on the wrong
record rewrites the wrong history.
### 2. Choose the successor mode
Exactly one of two shapes — ask if the user hasn't said:
- **New replacement decision** (the common case): call
`{"action": "supersede", "number": <old>, "title": "<new decision title>"}`.
The tool creates a `proposed` skeleton at the next free number with the `Supersedes` link
already in place, and flips the old record. The skelet