# 0000. ADR process and template

## Status

Accepted

## Context

We are about to make several architecture decisions about how the Qdrant
vector store is structured and used (ingestion, CRUD, and agent retrieval).
`docs/adr/README.md` currently has no convention for recording these
decisions. We need a lightweight, consistent format so future contributors
can understand *why* the system is built the way it is, not just *what* it
does.

## Decision

We will record architecturally significant decisions as Architecture Decision
Records (ADRs) under `docs/adr/`, using this convention:

- **Filename**: `NNNN-short-title.md`, zero-padded, monotonically increasing
  (`0000`, `0001`, `0002`, ...). The number is permanent once assigned.
- **Sections**, in this order:
  1. Title (`# NNNN. Title`)
  2. Status — one of `Proposed`, `Accepted`, `Superseded by NNNN`
  3. Context — the problem, constraints, and forces at play
  4. Decision — what we're doing, stated directly
  5. Consequences — `Positive` and `Negative` subsections
  6. Alternatives Considered — options we rejected and why
- **Immutability**: once an ADR is `Accepted`, it is not edited to reflect a
  changed decision. A changed decision gets a *new* ADR that sets the old
  one's status to `Superseded by NNNN` and links back to it. Small
  clarifications/typo fixes are fine to edit in place.
- **Scope**: only decisions with real architectural weight (data model,
  external system boundaries, protocols, cross-cutting concerns) get an ADR.
  Routine implementation choices do not.

## Consequences

### Positive
- Future contributors (and agents) can trace *why* the Qdrant schema, CRUD
  API, and retrieval pipeline look the way they do without re-deriving it
  from code.
- Decisions that turn out wrong are corrected via a visible trail
  (superseding ADRs) instead of silently rewritten history.

### Negative
- Adds minor overhead — anyone making a significant architectural change must
  also write or update an ADR.

## Alternatives Considered

- **No formal record, rely on commit messages/PR descriptions**: rejected —
  these are hard to discover later and don't survive squash-merges or
  history rewrites.
- **Full MADR template (with explicit "Decision Drivers" and scored option
  comparison tables)**: rejected as too heavyweight for this project's current
  size; we can adopt more structure later if needed via a new ADR.