---
name: ADR Template
description: Template for Architecture Decision Records inside the deployed instance. Immutable once accepted; superseded only by a new ADR. Mirrors the kit's own ADR practice and the BOOTSTRAP-BRIEF Section VII specification.
type: template
populated_from: per-decision; not a layer artifact
---

# ADR Template

This template is the canonical shape for ADRs inside the deployed instance. Copy this file to `decisions/ADR-NNNN-{short-imperative-title}.md` for each decision; never edit this template in place except to revise the standard.

When to write an ADR is governed by BOOTSTRAP-BRIEF Section VII. If two or more of the following are true, write an ADR:

- 2+ real options exist (not "do X vs. do nothing")
- The decision is not trivially reversible
- A future operator will wonder "why did we choose this?"
- The decision has cross-team or cross-product implications
- Regulatory, privacy, or cost considerations factor in

Decisions that typically warrant ADRs in any AI-shaped function:

- Model family and size per capability tier
- RAG vs. fine-tune vs. long-context injection
- Agent or workflow topology (single, orchestrator, hierarchical, swarm)
- Human-in-loop placement (input, mid, output, sampling)
- Retention posture (zero, redacted, full, tiered)
- Data residency and tenancy model
- Guardrail layering (input, prompt, output, post-hoc)
- Eval methodology (LLM-as-judge, human, synthetic, hybrid)
- Deprecation and migration strategy per model generation
- Build vs. buy for a capability
- Mirror direction and source for kit components
- Inbox-outbox pair declaration

---

# ADR-NNNN: {short imperative title}

- **Date:** YYYY-MM-DD
- **Status:** proposed | accepted | superseded by ADR-XXXX | deprecated
- **Reversibility:** high | medium | low
- **Deciders:** {names or roles}
- **Scope:** instance | cross-platform

## Context

{What situation is forcing this decision now? What constraints bound it? What upstream decisions (L0 through L3) are already locked? Be specific; "it came up in a meeting" is not context. Cite the data, the constraint, the deadline, the failure mode that surfaced the decision.}

## Decision

{The chosen option, stated as one sentence.}

## Options considered

### Option A: {name} [CHOSEN]

- **Summary:** ...
- **Pros:** ...
- **Cons:** ...

### Option B: {name}

- **Summary:** ...
- **Pros:** ...
- **Cons:** ...

### Option C: {name}

- **Summary:** ...
- **Pros:** ...
- **Cons:** ...

[Add more options if real. Two options is the minimum for an ADR; three or four is common; more than five suggests the decision is not yet ready.]

## Rationale

{Why the chosen option over the alternatives. Include the tradeoffs explicitly accepted. "It was the obvious choice" is not rationale; the explicit reasoning is.}

## Consequences

### Positive

- ...
- ...

### Negative

- ...
- ...

### Followups

- ...
- ...

## Reproducibility note (if applicable)

For decisions involving model, prompt, tools, or data choices, name the version pins that make this decision reproducible:

- **Model version:** ...
- **Prompt version:** ...
- **Tool set version:** ...
- **Data snapshot version:** ...

If any of these are not yet pinned, note that explicitly. Bumping any pin invalidates the eval evidence this ADR may have rested on; supersession is then required.

## Cross-references

- Layer this decision affects (L0-L7): ...
- Related ADRs (if any): ADR-...
- Inbox entries that escalated to this ADR (if any): ...
- Session logs that captured the discussion (if any): ...
