title: "Institutional Memory by Design: Our ADR Process"
date: 2026-02-17
author:
category: Governance
tags: [ADR, Documentation, Drupal, GitHub, AI-Ready]
Institutional Memory by Design: Our ADR Process
In a complex environment, the "why" behind our technical and operational decisions is our most valuable asset. To ensure these insights aren't lost to staff turnover or buried in email threads, we have formalized our Architectural Decision Records (ADR) process.
The Goal: Structured Entry, Portable Storage
We utilize a hybrid workflow that leverages the strengths of two distinct platforms: Drupal for the user interface and GitHub for long-term, AI-compatible storage.
1. Structured Capture in Drupal
We use Drupal as our "Entry Engine." Instead of asking team members to format complex Markdown by hand, they use a structured form with dedicated fields for:
- Status: (Proposed, Accepted, Superceded, or Deprecated)
- Context: The specific challenge or academic need we are addressing.
- Decision: The specific tool, policy, or architecture we are adopting.
- Consequences: The ripple effects—both positive and negative—of this choice.
2. Automated Publishing via ECA
Once an ADR reaches an "Approved" state, our ECA (Event-Condition-Action) workflow takes over. It automatically:
- Strips away the CMS-specific formatting.
- Converts the record into a clean Markdown (.md) file.
- Injects YAML metadata for easy indexing.
- Commits the file directly to our central GitHub repository via API.
Why We Move Records to GitHub
While Drupal is excellent for data entry, keeping the final records in a Git repository offers CHAS three major advantages:
AI-Ready Knowledge Base
By storing decisions as flat Markdown files, we make our institutional knowledge "machine-readable." This allows internal AI tools to index our decisions accurately, providing staff with instant answers regarding our technical standards and past precedents.
Version Control & Accountability
Every change to a decision is tracked with a timestamp and an author. This creates an immutable audit trail of how changes have evolved over time.
Portability and Durability
Decisions stored in GitHub are platform-independent. They live alongside our code and configurations, ensuring that even if our front-end tools change, our history remains accessible and intact.
This document serves as a guide on how we document and preserve our architectural integrity.