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
| Use an ADR |
Use DECISION_LOG.md |
| Architecturally significant, long-lived choice (platform, framework, tool, architecture pattern, infrastructure, data, security posture) |
Routine, reversible, day-to-day implementation decisions |
| A choice future maintainers must not silently reverse |
Session/context notes and rationale |
| A decision affecting regulated functionality, data integrity, interfaces, validation, or lifecycle risk |
— |
If in doubt, an ADR is the more durable, auditable choice.
ADR fields (append-only, immutable once written)
| Field |
Value / allowed values |
| ID |
ADR-XXXX — unique, never reused |
| Type |
Platform | Framework | Tool | Architecture | Infrastructure | Data | Security |
| Date |
Date of decision |
| Status |
proposed | approved | active | deprecated | superseded |
| Supersedes |
Reference to the ADR this one replaces (if any) |
| Review Date |
Scheduled re-evaluation date |
| Context |
Forces / problem driving the decision |
| Options Considered |
Alternatives evaluated |
| Decision |
The choice made |
| Rationale |
Why this option over the others |
| Consequences |
Trade-offs, follow-on constraints |
Procedure
- Propose — create the ADR with
Status: proposed; Context, Options
Considered, Decision, Rationale, Consequences are mandatory.
- 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.
- 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.
1---2name: agile-v-adr3description: Authoring, approval, immutability, and supersession of Architecture Decision Records (ADRs) in the Agile V lifecycle. Load when recording a significant, long-lived architectural, platform, tooling, or security decision.4license: CC-BY-SA-4.05---67# Instructions89An **Architecture Decision Record (ADR)** captures a significant, long-lived10technical decision. It is a distinct artifact from the append-only11`DECISION_LOG.md`: an ADR has a fixed field set, is immutable once written, and12is changed only by supersession. Agile V reserves the `ADR-XXXX` ID; this skill13backs it with an artifact and procedure.1415Requires **agile-v-core** loaded first. An ADR does not replace a REQ, risk16control, specification, or change record.1718## When to write an ADR1920| Use an **ADR** | Use `DECISION_LOG.md` |21|---|---|22| Architecturally significant, long-lived choice (platform, framework, tool, architecture pattern, infrastructure, data, security posture) | Routine, reversible, day-to-day implementation decisions |23| A choice future maintainers must not silently reverse | Session/context notes and rationale |24| A decision affecting regulated functionality, data integrity, interfaces, validation, or lifecycle risk | — |2526If in doubt, an ADR is the more durable, auditable choice.2728## ADR fields (append-only, immutable once written)2930| Field | Value / allowed values |31|---|---|32| ID | `ADR-XXXX` — unique, never reused |33| Type | Platform \| Framework \| Tool \| Architecture \| Infrastructure \| Data \| Security |34| Date | Date of decision |35| Status | proposed \| approved \| active \| deprecated \| superseded |36| Supersedes | Reference to the ADR this one replaces (if any) |37| Review Date | Scheduled re-evaluation date |38| Context | Forces / problem driving the decision |39| Options Considered | Alternatives evaluated |40| Decision | The choice made |41| Rationale | Why this option over the others |42| Consequences | Trade-offs, follow-on constraints |4344## Procedure45461. **Propose** — create the ADR with `Status: proposed`; Context, Options47 Considered, Decision, Rationale, Consequences are mandatory.482. **Approve** — the responsible human approver reviews (Human Gate etiquette,49 `agile-v-core` Directive 5). On approval, `proposed → approved → active`.50 Record approval evidence if the ADR gates a baseline or release.513. **Link** — relate affected requirements, risks, specifications, and change52 records via typed relationships (`agile-v-core` Directive 2).5354## Immutability & supersession5556- An active ADR is **never edited in place**.57- To reverse or amend, write a **new** ADR with `Supersedes: ADR-YYYY`, and set58 the old one to `Status: superseded` (the only permitted status edit on a59 written ADR).60- On `Review Date`, re-evaluate: keep `active`, or supersede.6162## Storage & traceability6364- One ADR per record under `.agile-v/adr/` (or a dedicated `ADR_LOG.md`),65 separate from the append-only `DECISION_LOG.md`.66- The `DECISION_LOG.md` may note an ADR promotion with a pointer to `ADR-XXXX`,67 but the ADR is the governed artifact.68- When an external ALM/requirements tool is bound via an extension, ADRs map to69 a dedicated item type in that tool — not folded into a decision-log item.7071## Halt conditions7273- ADR proposed without Context, Options, Decision, Rationale, or Consequences.74- In-place edit of an approved/active ADR (use supersession instead).75- Reuse of a retired `ADR-XXXX` ID.
Agile-V