Adr Supersede

adr-supersede

Creates new ADR superseding existing one, updates old ADR's status, maintains bidirectional cross-refs in both files and dir index.

> ADRs additive only: never delete or heavily rewrite accepted ADR. History preserved — old ADR stays readable.

---

Step 1 — Discover ADR directories

Same discovery as adr-create Step 1:

1. Search CLAUDE.md for heading containing ADR Locations. Collect bullet paths into adr_dirs, strip inline # comments.
2. If not found, fall back: scan for docs/adrs, decisions, architecture/decisions.
3. If empty, inform user and stop.

Step 2 — Select target directory

Multiple dirs → auto-suggest based on recent file context (same as adr-create Step 2). Present suggestion, wait for confirmation. Use confirmed path as target_dir.

Step 3 — Parse the argument and identify ADRs

Format:

[->new_num] [new decision text or reason]

Examples:

• 3 Switching from PostgreSQL to CockroachDB → old=3, new ADR doesn't exist yet, decision text provided
• 3->7 CockroachDB chosen to replace PostgreSQL → old=3, new=7 (ADR-0007 already exists), rationale provided
• 3->7 → old=3, new=7 already exists, no extra text

Resolution:

1. List files in target_dir matching NNNN-*.md.
2. Parse old_num. Zero-pad to 4 digits, find file as old_adr. No arg → display list and ask:

> Which ADR is being superseded? (enter the number)

1. Parse new_num if -> present:

• new_num provided + file exists → set new_adr, skip Steps 4–6, go to Step 7.
• new_num provided + file missing → treat as title/number hint for Step 6.
• No -> → create new ADR (proceed through all steps).

1. Confirm: Superseding: ADR-NNNN — . Proceed? (y/n)
2. old_adr already Superseded by ADR-MMMM → warn: ADR-NNNN is already superseded by ADR-MMMM. Supersede again? (y/n). Proceed only on confirm.

Step 4 — Understand the supersession

Gather from:

1. Read old ADR in full — Context, Decision, Consequences as baseline.
2. Conversation context — why old approach no longer works, what replacement is.
3. Arg — text after /adr-supersede used as supersession rationale.

Derive:

• new_adr_title: concise title for replacement.
• what_changed: why original replaced (new constraints, better alternatives, lessons learned).
• new_decision: new decision, specific and declarative.

If any can't be inferred, ask via AskUserQuestion. Batch questions: > I'm superseding ADR-NNNN (). To write replacement ADR: > > 1. What is the new decision? (e.g., "Use Redis for session storage instead of PostgreSQL") > 2. What changed that makes the old decision no longer appropriate?

Proceed only after all three pieces clear.

Step 5 — Draft the new ADR sections

Use old ADR as foundation + supersession context from Step 4.

Context

Start from old ADR's Context (original problem), then explain what changed (new constraints, growth, incidents, technology shifts, lessons learned that invalidate original decision). Reference old ADR by number.

Decision

New decision, clear and declarative. Contrast with old where helpful (e.g., "We will migrate from X to Y"). Include **Supersedes:** ADR- cross-ref.

Consequences

3–7 bullets: benefits of new over old, migration/transition costs, risks/tradeoffs of new decision, follow-up work, what becomes easier/harder vs. superseded approach.

If can't infer: > What are key benefits of new approach, and what migration/transition costs are anticipated?

Step 6 — Create the new ADR via adr-create

Invoke adr-create with:

• new_adr_title as decision summary arg
• Full supersession context (old ADR content + what changed + new decision) for section drafting

After completion, capture new file path and number as new_adr and next_num.

Open new ADR file, add cross-ref after **Date:**:

**Supersedes:** ADR-

Save file.

Step 7 — Link the superseded ADR

1. Open old_adr.
2. Find **Status:**. Replace value with Superseded by ADR-.
3. If -> path (new_adr already existed): add **Superseded by:** metadata after **Date:** if not present.
4. Save file.

Step 8 — Update the index

1. Open /README.md.
2. Find row for old ADR. Update Status to Superseded by ADR-.
3. New ADR just created by adr-create → index row already added, skip. New ADR already existed and not in index → add now.
4. Save README.md.

Step 9 — Confirm

> ADR- → ADR-: > Updated ADR-: Status → "Superseded by ADR-" > Updated index: /README.md > > Review the new ADR and change the Status to Accepted when finalised.

Step 10 — Post-write validation

Invoke adr-check scoped against superseded ADR (file modified in Step 7):

/adr-check 

Display all output to user.

• Structural FAIL: Block completion, prompt user to resolve:

> The superseded ADR has a structural validation failure. Please fix the issue above before confirming this supersession is complete.

• Style warnings only: Display and continue. Not blocking.

Note: new ADR (created via adr-create in Step 6) already validated by adr-create's post-write step — don't run adr-check again.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: samrom3
• Source: samrom3/claude-hyper-plugs
• License: MIT

Install and usage instructions live in the source repository linked above.