agentleFS
Atypical-ConsultingAtypical-Consulting/AdrMcp/.claude/skills/adr-supersede/SKILL.md

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

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
  1. Very specific:

    Re-point stragglers: If other ADRs relates-to the old one and should now track the replacement, add links with link_adrs.

    line 38
  2. Distinctive:

    Never delete or silently rewrite the superseded ADR — its value is the historical trail.

    line 43
  3. Very specific:

    After committing, the supersession chain should read cleanly end-to-end (find_related_adrs on the original should list the replacement in …

    line 46

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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 one superseded, link both ways — in one call). This is the common case.
  • No longer relevant, nothing replaces it → set_status to deprecated.
  • Was never adopted → set_status to rejected (only valid from proposed).
  • Just needs a small correction (typo, clarification) → this is NOT superseding; use update_adr on 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)

  1. Inspect the old decision. get_adr <old-id> and find_related_adrs <old-id> — know what already points at it so nothing is orphaned.
  2. 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.
  3. Preview supersede_adr(oldIdOrSlug, newTitle, context, decision, consequences, …) with previewOnly=true. Confirm the diff shows: new ADR created as accepted with a supersedes link, and the old ADR flipped to superseded with a superseded-by link.
  4. Commit by re-calling with previewOnly=false once approved.
  5. Re-point stragglers. If other ADRs relates-to the old one and should now track the replacement, add links with link_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_adrs on the original should list the replacement in its chain).

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.