Manage Adr

Manage ADRs

Record architectural decisions and proposals as ADRs, and maintain their history and relationships consistently.

Treat an ADR as a historical record of what was proposed or decided and why at a specific point in time, not as a document that should be continuously rewritten to match the current implementation.

Invariants

• Repository ADR conventions take precedence over this skill's defaults.
• Do not present unagreed proposals as accepted decisions.
• When asked to document a proposal, use the repository's draft or Proposed convention.
• Preserve existing ADR decision bodies as historical records unless modification is explicitly in scope.
• When the meaning of an accepted decision changes, record the change in a follow-up ADR by default.
• Distinguish decision-body changes from status, relationship, and implementation-status metadata changes.
• Modify only the requested scope; do not opportunistically clean up surrounding text.
• Do not ask again for facts or decisions already established.
• Do not interpret an ADR request as authorization to implement code, create issues, or produce unrelated documents.
• Do not use implementation progress as a decision status.

Inspect Repository Conventions

Before creating or modifying an ADR, inspect as applicable:

1. Repository instructions such as AGENTS.md
2. ADR directory and its index or README
3. ADR template
4. The 2–3 most recent ADRs
5. The target ADR and directly related ADRs
6. ADR generation or validation scripts, CLIs, and CI rules

Determine:

• ADR location
• filename and numbering convention
• document language
• decision-status vocabulary
• implementation-status convention, if any
• relationship vocabulary and placement
• document structure
• index update requirements
• link format
• existing automation

Preserve existing status names, relationship names, frontmatter, and link formats.

Do not introduce a new field or relationship name when the repository already has an equivalent convention.

Classify the Change

Before acting, determine whether the request concerns:

• a new architectural proposal or decision
• an extension of an existing decision
• a partial amendment
• replacement of an existing decision
• a reference-only relationship
• a decision-status change
• an implementation-status change
• a relationship or link change
• an implementation detail
• a documentation-only correction

Do not create a new ADR for implementation-only changes.

Do not treat a change to the meaning of an architectural decision as a simple documentation edit.

If the user requests only a draft or review, do not modify files.

Create a New ADR

Record only what is necessary:

• problem or context
• relevant constraints
• proposal or decision
• rationale
• significant alternatives
• consequences and trade-offs
• relationships to existing ADRs when relevant

For a follow-up ADR, identify the affected decision and scope of change clearly.

If the ADR is not yet agreed, represent it using the repository's proposal or draft state rather than wording it as an accepted decision.

Do not rewrite historical ADRs to match the current implementation.

Keep implementation procedures, operational instructions, and usage guidance in appropriate technical documentation when they are not part of the architectural decision.

Do not create an ADR for every implementation discovery or bug fix.

Decision Relationships

Choose relationships based on the validity of the existing decision and the role of the new decision, not on the amount of text changed.

Extends

Use when:

• the existing decision remains valid
• the new ADR adds scope, capability, or another application of that decision

Do not change the existing ADR's status merely because it is extended.

Amends

Use when:

• specific conditions or parts of the existing decision change
• the core decision remains valid

State the affected condition, section, or scope clearly.

For partial changes, consider Amends before Supersedes.

Supersedes

Use when:

• the existing ADR's core decision no longer represents the current decision
• the new ADR replaces that decision

Do not use Supersedes for a simple partial modification.

Unless the repository explicitly supports scoped supersession, represent partial changes as Amends.

When adding Supersedes, follow repository conventions for updating the previous ADR's status and reverse relationship.

Related

Use when ADRs are contextually related but neither changes the other's decision.

Do not weaken an actual decision-change relationship into Related.

Manage Relationships

• Maintain reverse relationships when the task scope permits.
• Follow repository-specific relationship names when they differ from these defaults.
• If existing ADRs must not be modified, record the relationship only where modification is permitted.
• Preserve existing relationships and add only what is required.
• Do not create duplicate relationships or self-references.
• Do not reference ADRs that do not exist.
• Do not guess when the relationship target is materially ambiguous.
• A proposed follow-up ADR does not yet amend, extend, or supersede an accepted decision in effect.
• Follow repository conventions for representing relationships proposed but not yet accepted.
• Do not change an existing ADR's effective status, reverse relationship, or other metadata in a way that implies a proposed change has already taken effect.
• Apply effective relationship and status changes when the follow-up decision becomes accepted, unless repository conventions define a different lifecycle.

Modify Existing ADRs

Within the requested scope and where repository conventions permit, direct edits may be appropriate for:

• typos
• broken links
• incorrect numbering or metadata
• clear documentation errors that do not change meaning
• edits explicitly requested by the user

A follow-up ADR is usually more appropriate for:

• changes to decision meaning
• new architectural constraints
• changes to the selected technology or approach
• changes to part of an existing architectural policy
• complete replacement of an existing decision

When asked to change only metadata, modify only the requested fields.

Do not rewrite historical prose to reflect the current implementation or append implementation results to the original decision body unless explicitly required.

Manage Status

Use the repository's decision-status vocabulary.

Common meanings include:

• Proposed: under review or not yet agreed
• Accepted: the decision has been approved
• Rejected: considered but not adopted
• Superseded: replaced by a later decision
• Deprecated: no longer recommended

Accepted does not mean implementation is complete.

Do not use implementation progress as a decision status.

If the repository has a separate implementation-status field, maintain it independently and only within the requested scope.

Do not introduce an implementation-status field or values such as Implemented unless requested or required by repository conventions.

Ask Only When Necessary

Ask for clarification only when ambiguity would materially change the result.

Examples:

• the target ADR is unclear
• there is insufficient evidence to choose between Amends and Supersedes
• a change could reasonably belong to multiple ADRs
• it is unclear whether reverse relationships may also be modified
• repository ADR conventions conflict

When asking, identify the target ADR, candidate relationship, affected fields, and consequences of the alternatives.

Do not reconfirm decisions already approved or established by repository conventions.

Apply the Change

When creating an ADR:

1. Check for filename or number collisions.
2. Follow the existing naming, numbering, language, and document structure.
3. Record required relationships according to the ADR's current lifecycle state.
4. Verify links.
5. Update the index when repository conventions require it.

When modifying an ADR:

1. Change only the requested scope.
2. Preserve unrelated content and relationships.
3. Keep decision status and implementation status independent.
4. Do not remove existing links when adding relationships.
5. Do not apply effective supersession or amendment metadata from a merely proposed follow-up ADR.

Use Existing Automation

Prefer repository-provided ADR tooling when available, such as:

• numbering scripts
• template generators
• link validators
• ADR linters
• adr-tools
• repository-specific CLIs
• CI validation scripts

Confirm that the tool follows repository conventions before using it.

Do not modify ADR content merely to hide a validation failure.

If no validation tool exists, perform the required checks directly.

Validate

After the change, verify as applicable:

• filename or ADR number is unique
• required headers or frontmatter are present
• referenced ADRs exist
• relationship direction is correct
• relationship metadata matches the ADR's lifecycle state
• proposed follow-up ADRs have not prematurely changed existing ADR status or effective relationships
• reverse relationships exist when required and effective
• existing relationships were preserved
• amendment scope is clear
• Supersedes was not used for an ordinary partial change
• no duplicate relationship or self-reference exists
• links are valid
• required indexes are updated
• only requested metadata or body content changed
• decision and implementation statuses remain distinct
• repository validation tools pass

Completion Response

Keep the completion response concise.

Report:

• ADRs created
• ADRs modified
• status or relationship changes
• validations performed
• validation failures or unresolved checks

Do not claim that implementation, documentation, or issue work was completed unless it was actually performed.