Skip to content

[GOV] Adopt decision records (ADR practice) across the project #6

Description

@nnworkspace

Governance area

Conventions and project memory. Touches Communication and, as a follow-up,
Linting.

Current situation

The project has no defined mechanism for recording significant, hard-to-reverse
decisions: toolchain choices, structural conventions, deferred migrations, the
rejection of alternatives. Today the reasoning behind such decisions survives
only in meetings, chat, and the memory of whoever was present. Version-control
history records what changed and when, but it is a forensic substrate, not a
readable one. A future builder, reviewer, or auditor has no durable answer to
"why was it done this way, and what else was considered?"

Proposed change

Adopt a decision record practice (the industry "Architecture Decision
Record" practice, generalised beyond architecture to any decision of
consequence):

  • Add a normative governance document 00-project-governance/decision-records.md
    defining the practice: what belongs in a record, scope, lifecycle, the
    immutability rule, the record template, and enforcement.
  • Establish the decisions/ folder convention: PDR- records for project-wide
    decisions in 00-project-governance/decisions/; DR- records for
    repository-local decisions in each repository's own decisions/ folder.
  • Add PDR-0000 as the meta-record that adopts the practice, plus a folder
    README.md and index.
  • Register the new document in the governance README.md and in
    00-project-governance/manifest.yaml.

Rationale

A decision record captures the reasoning as it stood at decision time. Made
immutable once accepted, it becomes durable evidence rather than a mutable
wiki page: the supersession chain stays readable as whole documents, and the
record survives repository migrations and version-control history rewrites. The
discipline is small and the cost it prevents, institutional amnesia, is large.

Impact

Affects every repository in the project and all builders, legal, technical,
operational, and audit. The change is non-breaking: it adds a convention and
leaves existing artefacts untouched.

Transition considerations

  • The initial change is documentation-only.
  • SET-GOV in manifest.yaml may warrant a version bump per the configuration
    management strategy; the new file has been added to contains: either way.
  • A matching "Decision Records" section in linting-rules.md (formal LINT-
    rules) is a sensible follow-up so the immutability and numbering checks become
    mechanical.
  • Each repository adopts its own DR-0000 over time.

References

  • 00-project-governance/decision-records.md
  • 00-project-governance/decisions/PDR-0000-adopt-decision-records.md
  • 00-project-governance/decisions/README.md
  • 00-project-governance/communication-and-project-management.md
  • 00-project-governance/linting-rules.md

Metadata

Metadata

Assignees

No one assigned

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions