ADR template

Copy this template for every architecture decision record.

ADR template

Copy this template into content/<product>/<N>.decisions/ or content/1.platform/5.decisions/ with a filename of the form YYYY-MM-DD-<slug>.md. Fill in every section — an ADR with missing sections is worse than no ADR.

Frontmatter block

---
title: <decision — imperative or noun phrase, not a question>
description: <one-line summary, used in the decisions index>
navigation:
  icon: i-lucide-file-text
---

Body template

# <decision>

**Status:** proposed | accepted | superseded-by [<new decision>](/<path>/<slug>)
**Date:** YYYY-MM-DD

## Context

What forces are at play? What constraints, requirements, or existing decisions frame this choice? Keep this grounded in facts — no speculation, no "we might want."

## Decision

The decision itself, in declarative form. "We use X because Y." One paragraph ideally.

## Consequences

What becomes easier. What becomes harder. What new obligations the decision creates. Be honest about downsides.

## Alternatives considered

Each alternative: one sentence naming it, one or two sentences on why it was rejected. No straw men — only alternatives that were genuinely on the table.

Writing rules

Status transitions: an accepted ADR is never edited in place. To revise, write a new ADR that supersedes it and flip the old one's status to superseded-by with a link to the replacement.
Keep ADRs short — usually under 300 words. If it's longer, the decision is probably too big; split it.
Link to code, specs, or other ADRs whenever a claim rests on them. Root-relative for internal, absolute URL for external.
Dates are the day the decision was made, not the day the doc was written (if they differ, add a note).

Topology

Deployment diagram — PCTs, Cloudflare tunnels, DB host, Valkey, Ollama placement.

Conventions

Writing style, frontmatter, diagrams, cross-linking, and ADR format for ValkymIA internal docs.