Working with ADRs

ADRs (Architectural Decision Records) document significant design choices. They explain why things are built a certain way.

Creating ADRs

govctl adr new "Use Redis for caching"

This creates a TOML file in gov/adr/ with the decision context.

ADR Structure

ADRs contain:

Context — The situation requiring a decision
Decision — What was decided
Consequences — Expected outcomes (positive and negative)
Alternatives — Options considered with pros, cons, and rejection reasons (per [[ADR-0027]])
Status — proposed, accepted, rejected, or superseded

Editing ADRs

ADRs are TOML files — edit them directly in your editor or use govctl to get/set fields:

# Get specific field
govctl adr get ADR-0003 status

# Set field value
govctl adr set ADR-0003 status accepted

For alternatives (pros/cons/rejection reason), path-based edits are supported:

# Before: remove and re-add whole alternative to change one pro
govctl adr remove ADR-0001 alternatives "Option 3" --exact
govctl adr add ADR-0001 alternatives "Option 3: Use Raft" --pro "Updated pro"

# After: direct nested edit
govctl adr set ADR-0001 alt[2].pro[0] "Updated pro"

Status Lifecycle

proposed → accepted → superseded
         ↘ rejected

Accept a Decision

When consensus is reached:

govctl adr accept ADR-0003

Deprecate

When a decision is no longer relevant:

govctl adr deprecate ADR-0003

Supersede

When a new decision replaces an old one:

govctl adr supersede ADR-0001 --by ADR-0005

This marks ADR-0001 as superseded and records ADR-0005 as its replacement.

Listing ADRs

govctl adr list
govctl adr list accepted    # Filter by status

Why TOML?

ADRs use TOML (not JSON or YAML) because:

Comments allowed — Humans can annotate inline
Multi-line strings — Clean """ blocks for prose
No YAML ambiguity — NO stays NO, not false
Round-trip stable — Deterministic serialization

Keyboard shortcuts

govctl