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 | 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 1. **Propose** — create the ADR with `Status: proposed`; Context, Options Considered, Decision, Rationale, Consequences are mandatory. 2. **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. 3. **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.