Skip to content

Decision Log (ADR) with Reversibility

Intent

Capture key decisions as lightweight ADRs with explicit revisit triggers.

Structure

An ADR decision log is a small, versioned set of markdown documents stored alongside source. It creates a durable index of decisions that affect the IG’s structure and downstream implementers.

  • ADR directory: a dedicated folder (e.g., docs/adr/) with numbered, immutable records
  • Standard template: context → decision → consequences → alternatives considered
  • Linkage: each ADR links to PRs/issues/meeting notes and to affected artifacts (profiles, terminology, build config)
  • Index: a simple table of contents so decisions can be discovered quickly
  • Status model: proposed/accepted/superseded with explicit revisit triggers

Key Components

ADR template

  • Standardize decision records: context → decision → consequences
  • Include alternatives considered and why they were rejected
  • Add links to issues, PRs, and meeting notes
  • Keep ADRs short (1–2 pages)
  • Make ADRs easy to discover from the repo root

Decision owner

  • Assign one accountable person per ADR
  • Define who must be consulted vs informed
  • Clarify escalation path when agreement isn’t possible
  • Ensure decision owners rotate if needed but accountability remains clear
  • Keep ownership aligned with governance structure

Revisit triggers

  • Record explicit conditions that force a decision review
  • Common triggers: new IG dependency, scope shift, ballot feedback, validator changes
  • Use dates or milestone checkpoints to prevent decisions from stagnating
  • Mark impacted artifacts so changes are scoped
  • Update triggers when reality changes

Status

  • Use a small lifecycle: proposed → accepted → superseded
  • Mark superseding ADRs and keep history
  • Avoid ‘draft forever’ by setting deadlines
  • Reflect status in PR checks (e.g., required ADR for certain changes)
  • Keep the ADR index up-to-date

Behavior

Decision lifecycle

ADRs work when they’re lightweight and enforced. The behavior is about making decisions visible, easy to reference, and easy to revisit when assumptions change.

Create

  • Create an ADR whenever a change affects canonical/package/versioning, governance, profiling strategy, or terminology policy.
  • Time-box decision-making and document alternatives considered.
  • Assign an accountable owner and list consulted/informed roles.

Enforce

  • Require ADR references in PRs for changes in certain paths (e.g., ig.ini, canonical, dependencies).
  • Keep the ADR index updated as part of the PR checklist.
  • Use revisit triggers to avoid stale decisions living forever.

Revisit

  • When a trigger fires (dependency change, ballot feedback, scope split), open a short PR that proposes a superseding ADR.
  • Record the new decision and mark the old ADR superseded.
  • Communicate decision impacts in release notes and migration guidance.

Benefits

  • Fast decisions with rationale
  • Avoid re-litigation

Trade-offs

  • Requires enforcement

Example

ADR: canonical base + packageId; revisit if scope splits or governance changes.