adr-supersede
Skill1 starsChanged 4 months agoMITView on GitHub
Use when an existing architectural decision is being changed, replaced, retired, reversed, or deprecated — the team changed its mind and a prior ADR no longer reflects reality. Drives the correct lifecycle transition and bidirectional linking via the AdrMcp MCP tools (supersede_adr, set_status, link_adrs, find_related_adrs). Triggers on "supersede ADR-000X", "we changed our mind about", "replace/retire this decision", "this ADR is out of date", "mark as deprecated/superseded", "reverse decision".
In this repository3 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- adr-authorSkill
- adr-reviewSkill
The file
We split this skill into the rules it gives an agent
3 rules. About 0 are common, 1 is distinctive, and 2 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 38
Re-point stragglers: If other ADRs relates-to the old one and should now track the replacement, add links with link_adrs.
- Distinctive: line 43
Never delete or silently rewrite the superseded ADR — its value is the historical trail.
- Very specific: line 46
After committing, the supersession chain should read cleanly end-to-end (find_related_adrs on the original should list the replacement in …
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Superseding a decision
You retire or replace a prior decision correctly — preserving history rather than editing the past. ADRs are immutable records: you don't rewrite an accepted decision, you supersede it with a new one and link them.
Requires the AdrMcp MCP server (tools
supersede_adr,set_status,link_adrs,find_related_adrs,get_adr). If unavailable, ask the user to connect it first.
First, pick the right move
- Replaced by a new decision →
supersede_adr(create the replacement, mark the old onesuperseded, link both ways — in one call). This is the common case. - No longer relevant, nothing replaces it →
set_statustodeprecated. - Was never adopted →
set_statustorejected(only valid fromproposed). - Just needs a small correction (typo, clarification) → this is NOT superseding; use
update_adron the original instead.
Remember the lifecycle the server enforces: proposed → accepted → {deprecated, superseded},
and proposed → rejected. You can't supersede something that was never accepted.
Workflow (replacement case)
- Inspect the old decision.
get_adr <old-id>andfind_related_adrs <old-id>— know what already points at it so nothing is orphaned. - Frame the new decision with the same rigor as
adr-author: what changed in the forces since the original? The new Context should explain why the old choice no longer holds, not just restate the new one. - Preview
supersede_adr(oldIdOrSlug, newTitle, context, decision, consequences, …)withpreviewOnly=true. Confirm the diff shows: new ADR created asacceptedwith asupersedeslink, and the old ADR flipped tosupersededwith asuperseded-bylink. - Commit by re-calling with
previewOnly=falseonce approved. - Re-point stragglers. If other ADRs
relates-tothe old one and should now track the replacement, add links withlink_adrs.
Guardrails
- Never delete or silently rewrite the superseded ADR — its value is the historical trail.
- The new ADR must say what the old one got wrong or what changed; a supersession without a reason is just churn.
- After committing, the supersession chain should read cleanly end-to-end
(
find_related_adrson the original should list the replacement in its chain).
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

