Skip to main content

ADR-000 - Governance through Decision Records (ADRs)

  • Status: Accepted
  • Decision Date: 2026-07-22
  • Deciders: PIES Design Team, governance stakeholders
  • Category: Process, Governance

Context​

NR-PIES is establishing a formal ontology and data standard to provide clear business semantics and data models for the permitting domain, structurally inspired by HL7 FHIR. This effort involves numerous design decisions across schemas, system boundaries, and architectural tradeoffs. Extensive prior research (data harmonization, conceptual modeling, past standards iterations) demonstrates the complexity and depth of these decisions. Without a formal process to document these decisions, their rationale, and alternatives considered, future implementers and maintainers lack visibility into what was decided and why. This gap makes it difficult to govern evolution, audit changes, and understand the design intent behind the specification.

Decision​

Adopt Architecture Decision Records (ADRs) as the formal mechanism for documenting design decisions, engineering tradeoffs, and boundary decisions in NR-PIES. All significant architectural, schema, and governance decisions will be recorded as ADRs, reviewed by the governance team, and maintained alongside the specification.

Rationale​

ADRs provide a lightweight, versionable, and auditable approach to decision documentation. They make design intent explicit and discoverable for future maintainers and implementers. Unlike Confluence or informal notes, ADRs are versioned with the specification, linked to specific commits, and structured for consistency. This creates a clear paper trail for how and why PIES evolved, supporting both governance transparency and technical continuity.

Assumptions​

  • Decisions documented early are more valuable than retrofitted records.
  • The governance team is willing to review and approve ADRs as part of the change process.
  • ADRs will be maintained alongside the specification in version control.
  • ADRs will be reviewed as part of pull request workflows, ensuring visibility and approval before merge.

Options Considered​

  • ADRs (chosen): Formal, versioned, linked to commits, structured template, part of specification history.
  • Confluence documents: Easy to write, but scattered, not versioned with code, difficult to link to specific decisions.
  • Informal decision logs: No enforced structure, no audit trail, easy to forget or lose context.

Consequences​

Positive​

  • Clear decision trail and governance maturity for the specification.
  • Future maintainers understand design intent and tradeoffs without asking for context.
  • ADRs provide an auditable record of how PIES evolved and why.
  • Decisions are immutable and linked to specific points in specification history.

Negative​

  • Overhead of writing and reviewing ADRs for each significant decision.
  • Requires discipline to avoid empty or low-quality ADR entries.
  • Reviews may slow down decision making if not balanced with speed requirements.

References​

  • None yet. This is the foundational ADR for the PIES governance process.