ADR Superseding Prompt Template

This prompt is for architects and engineering leads who need to formally replace or update an existing Architecture Decision Record (ADR) with a new decision. The job-to-be-done is producing a superseding ADR that explicitly references the original decision, explains what changed and why, and captures the migration implications for affected systems and teams. This is not a prompt for creating a net-new ADR from scratch, nor for making minor amendments or status updates to an existing record. Use it when the original decision is no longer valid and must be fully replaced by a new architectural choice.

The ideal user has the original ADR text, the new decision context, and an understanding of which downstream ADRs, services, or teams are affected by the change. Required inputs include: the original ADR (full text or structured record), the new decision and its rationale, the trigger for the change (e.g., new constraints, failed assumptions, technology evolution), and a list of affected downstream ADRs or systems. Do not use this prompt when the original decision is still valid but needs a status update, when you are drafting a brand-new decision with no predecessor, or when the change is a minor clarification rather than a substantive reversal or replacement. For those cases, use the ADR Status Update Prompt Template or the standard ADR Generation Prompt Template instead.

The output is a complete superseding ADR that includes a traceability section linking to the original, a clear statement of what changed, and a migration impact assessment. Because superseding an ADR can invalidate downstream decisions and trigger implementation rework, this workflow requires human review before the new ADR is accepted. The prompt alone is not a substitute for architectural judgment. After generating the draft, validate that all referenced ADRs still exist, that the rationale for superseding is sound, and that affected teams are notified. If the change affects systems in production, pair this prompt with the ADR Dependency Mapping Prompt to assess the full blast radius before finalizing.

This prompt template is designed to produce a complete superseding Architecture Decision Record (ADR) when an existing decision must be replaced or updated. It forces the model to reference the original ADR explicitly, explain the trigger for change, document what is different, and capture the migration path. The template uses square-bracket placeholders that you replace with your specific context before sending the prompt to a model. Every placeholder is required unless marked optional—omitting one will degrade the output quality.

textCopy
You are an experienced software architect writing a superseding Architecture Decision Record (ADR).
Your task is to produce a new ADR that explicitly replaces an existing one.

## Inputs
- Original ADR to supersede:
[ORIGINAL_ADR_TEXT]

- Reason for superseding (trigger, new evidence, constraint change):
[SUPERSEDING_REASON]

- New decision and context:
[NEW_DECISION_DETAILS]

- Affected downstream ADRs or systems (optional):
[AFFECTED_DOWNSTREAM]

- Migration notes or breaking changes (optional):
[MIGRATION_NOTES]

- ADR template format to follow:
[ADR_TEMPLATE_FORMAT]

## Output Schema
Produce a superseding ADR with these sections:
1. **Superseding Header**: ADR number, title, status (Supersedes [ORIGINAL_ADR_ID]), date, and authors.
2. **Supersession Statement**: A clear statement that this ADR supersedes [ORIGINAL_ADR_ID]. Include the original ADR's title and date for traceability.
3. **Change Trigger**: What changed—new evidence, constraint shift, incident, or re-evaluation—that made the original decision no longer correct.
4. **Context**: The current problem context, constraints, and stakeholders. Note what context differs from the original ADR.
5. **Decision**: The new decision, stated clearly and unambiguously.
6. **What Changed from Original**: A structured comparison table or list showing what is different from the original ADR and why each change matters.
7. **Options Considered**: Alternatives evaluated for this new decision, including the original decision as one option. Include trade-offs.
8. **Migration Implications**: Breaking changes, migration steps, deprecation timeline, and affected systems or downstream ADRs.
9. **Consequences**: Positive and negative consequences of adopting this new decision.
10. **Downstream Impact**: Which ADRs, systems, or teams need to be notified or updated.
11. **References**: Link to the original ADR, related ADRs, and evidence sources.

## Constraints
- Never claim the original ADR was wrong without explaining why it was correct at the time and what changed.
- If [AFFECTED_DOWNSTREAM] is provided, explicitly address each affected ADR or system.
- If [MIGRATION_NOTES] is provided, incorporate them into the Migration Implications section.
- Use the format specified in [ADR_TEMPLATE_FORMAT]. If none is provided, use the standard Michael Nygard ADR format.
- Mark any sections where information is missing with "[TO BE COMPLETED]" rather than fabricating content.
- Preserve traceability: every claim about the original ADR must be verifiable from [ORIGINAL_ADR_TEXT].

To adapt this template, replace each square-bracket placeholder with your actual content. The [ORIGINAL_ADR_TEXT] should contain the full text of the ADR being superseded—do not summarize it yourself. The [SUPERSEDING_REASON] is the most critical field; it must explain why the change is happening now, not just what the new decision is. If you do not have downstream ADR information, remove the [AFFECTED_DOWNSTREAM] placeholder and the corresponding constraint, but keep the Downstream Impact section with a note that downstream analysis is pending. For high-stakes architectural changes, always route the generated ADR through human review before marking the original as superseded in your ADR repository.

The ADR Superseding Prompt is not a one-shot generation tool; it is a stateful operation that mutates your decision log. The implementation harness must enforce that the original ADR exists, capture the relationship between the old and new records, and prevent orphaned references. Wire this prompt into your ADR management system—whether that is a git repository of markdown files, a documentation site, or an internal tool—so that every superseding record includes a validated backlink to the original ADR and a forward reference in the original indicating it has been superseded.

The harness should perform pre-generation validation: confirm the [ORIGINAL_ADR_ID] exists in the repository, extract its current status (accepted, proposed, deprecated), and reject the operation if the original is already superseded or deprecated unless an explicit force flag is set. After the model generates the new ADR, run post-generation checks: verify the supersedes field matches the input ID, confirm all required sections are present (context, decision, rationale, migration implications), and check that the new ADR does not duplicate the original's content verbatim. For high-risk architectural changes, route the generated ADR to a human review queue before it is committed. Log the model, prompt version, and validation results for auditability.

Model choice matters here. Use a model with strong instruction-following and long-context handling because the prompt must process the full original ADR plus any downstream ADRs that reference it. If your ADR repository is large, implement a retrieval step that fetches only the original ADR and ADRs that explicitly reference it, rather than stuffing the entire repository into context. For retry logic, if validation fails on missing sections or malformed references, re-prompt once with the specific validation errors injected into [CONSTRAINTS]. If the second attempt fails, escalate to a human author with the partial output and error details. Do not silently accept a superseding ADR that breaks the reference chain.