/adr:supersede

Supersede ADR

Create a new ADR that supersedes an existing one, with proper bidirectional linking.

Process

Parse arguments to get existing ADR ID and new title
Verify existing ADR exists and is supersedable
Gather supersession context (why superseding)
Create new ADR with “Supersedes ADR-XXXX”
Update old ADR status to “superseded” with “Superseded by ADR-YYYY”
Update index with both changes
Git commit if configured

Argument Parsing

Required arguments:

<existing-adr-id>: The ADR being superseded
<new-title>: Title for the new ADR

Pre-Supersession Checks

Verify the existing ADR:

Exists
Is in “accepted” or “deprecated” status
Is not already superseded

If already superseded, warn and suggest:

Supersede the current successor instead
Or proceed with supersession chain

Context Gathering

Ask for supersession context:

Reason: “Why is the original ADR being superseded?”
Changes: “What key changes does the new decision make?”
Migration: “Is there a migration path from old to new?”

New ADR Creation

Create new ADR with:

Next sequential number
User-provided title
Status: “proposed” (or “accepted” if immediate)
Supersedes section linking to old ADR
Context includes reference to superseded decision

Template addition:

## Status

Proposed

Supersedes [ADR-{old_id}](./0001-old-title.md)

## Context and Problem Statement

This decision supersedes ADR-{old_id} because {reason}.

{Additional context}

Old ADR Update

Update the superseded ADR:

## Status

Superseded by [ADR-{new_id}](./0002-new-title.md)

**Note**: This ADR has been superseded. See ADR-{new_id} for the current decision.

Index Update

Update README.md:

Add new ADR entry
Update old ADR status to “superseded”
Add supersession relationship in “Related” column if present

Supersession Chain

If superseding an ADR that itself superseded another:

Document full chain in new ADR
Update “More Information” section with history

Example:

## More Information

This is the third iteration of our database decision:
- ADR-0001: Original MySQL selection (superseded)
- ADR-0005: Migration to PostgreSQL (superseded by this ADR)
- ADR-0012: This ADR - Move to managed PostgreSQL

Git Integration

If enabled, create commit:

git add {new_adr} {old_adr} {readme}
git commit -m "docs(adr): ADR-{new_id} supersedes ADR-{old_id}

{new_title}

Supersedes ADR-{old_id}: {old_title}"