agile-v/agile_v_skills/agile-v-adr

Instructions

An Architecture Decision Record (ADR) captures a significant, long-lived technical decision. It is a distinct artifact from the append-only DECISION_LOG.md: an ADR has a fixed field set, is immutable once written, and is changed only by supersession. Agile V reserves the ADR-XXXX ID; this skill backs it with an artifact and procedure.

Requires agile-v-core loaded first. An ADR does not replace a REQ, risk control, specification, or change record.

When to write an ADR

If in doubt, an ADR is the more durable, auditable choice.

ADR fields (append-only, immutable once written)

Procedure

1. Propose — create the ADR with Status: proposed; Context, Options

Considered, Decision, Rationale, Consequences are mandatory.

1. Approve — the responsible human approver reviews (Human Gate etiquette,

agile-v-core Directive 5). On approval, proposed → approved → active. Record approval evidence if the ADR gates a baseline or release.

1. Link — relate affected requirements, risks, specifications, and change

records via typed relationships (agile-v-core Directive 2).

Immutability & supersession

• An active ADR is never edited in place.
• To reverse or amend, write a new ADR with Supersedes: ADR-YYYY, and set

the old one to Status: superseded (the only permitted status edit on a written ADR).

• On Review Date, re-evaluate: keep active, or supersede.

Storage & traceability

• One ADR per record under .agile-v/adr/ (or a dedicated ADR_LOG.md),

separate from the append-only DECISION_LOG.md.

• The DECISION_LOG.md may note an ADR promotion with a pointer to ADR-XXXX,

but the ADR is the governed artifact.

• When an external ALM/requirements tool is bound via an extension, ADRs map to

a dedicated item type in that tool — not folded into a decision-log item.

Halt conditions

• ADR proposed without Context, Options, Decision, Rationale, or Consequences.
• In-place edit of an approved/active ADR (use supersession instead).
• Reuse of a retired ADR-XXXX ID.