chatbot_v3/docs/adr/0000-adr-template.md

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.