supersede-decision

Mark an architecture decision record as superseded by a newer decision with validated reverse links.

11|1|Updated Jul 25, 2025

Search Tags:#markdown #adr #lifecycle #sdlc #decision records #architecture decision #supersede

Ready to run

npx skills add https://github.com/tomzx/agents --skill supersede-decision-tomzx

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: supersede-decision
Source: https://github.com/tomzx/agents/tree/main/skills/supersede-decision
Command: npx skills add https://github.com/tomzx/agents --skill supersede-decision-tomzx

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? When a new Architecture Decision Record (ADR) replaces an older one, teams often edit decision files by hand, leading to inconsistent statuses, missing reverse links, and broken supersession chains. This Skill automates the lifecycle transition so both records stay in sync and invalid relationships are rejected before any file changes. ## Core Features & Use Cases - Bidirectional status updates: Sets the old decision to `Superseded by [N]` in frontmatter and body, and adds a `supersedes` reverse link to the new decision. - Relationship validation: Refuses cycles, re-superseding terminal decisions (Deprecated or already Superseded), self-references, and retired replacements. - Flexible argument resolution: Accepts bare numbers (`7`), zero-padded numbers (`0007`), or filenames (`7-use-redis.md`) to locate decisions under `.sdlc/knowledge/decisions/`. - Use Case: After adopting a new ADR replacing memcached with Redis, run `/supersede-decision 3 9` to mark decision 3 as superseded by 9 and record the reverse link automatically. ## Quick Start Ask the agent to supersede decision 3 with decision 9 by running the supersede-decision skill with those two decision numbers.

Frequently Asked Questions about supersede-decision

High-intent search queries and answers about installing and using this skill.

FAQPage Schema

How do I mark an ADR as superseded by a newer decision?▼

Run the supersede-decision skill with the old and new decision identifiers, such as `/supersede-decision 3 9`. It sets the old decision's status to `Superseded by [N]` and adds a `supersedes` reverse link to the new decision's frontmatter and body.

How to reference architecture decisions by number or filename?▼

Both arguments accept a bare number like `7`, a zero-padded number like `0007`, or a filename like `7-use-redis.md`. Numbers resolve to the file `N-<slug>.md` in the decisions directory.

Can I supersede a decision that is already deprecated or superseded?▼

No. Terminal states cannot be re-superseded; the skill refuses and points you to the live decision at the head of the chain. It also refuses if the replacement decision is itself Deprecated or Superseded.

What happens if the new decision already supersedes the old one?▼

The skill detects this as a cycle by following the `supersedes` links from the new decision and refuses the operation, since the relationship is already recorded in the opposite direction. No files are changed on refusal.

When should I use deprecation instead of superseding a decision?▼

Use deprecation when a decision should retire with no successor; that transition is handled by the review-decision skill. Supersede-decision is only for recording that a specific replacement ADR has been adopted.