# Decision records

> The decision record template used on every build: context, options, decision, consequences and when to revisit, with a worked example.

- Web page: https://www.alesanalytics.com/docs/decision-records
- Markdown: https://www.alesanalytics.com/docs/decision-records.md
- Last updated: 2026-11-08
- Publisher: Ales Analytics

How we build. How design choices are written down and revisited. Published 2026-11-08. Last reviewed 2026-11-08. Reviewed by Ales Analytics engineering.

## In one paragraph

Design choices on a build are recorded as short decision records: what was decided, what else was considered, and why. A record makes a choice reviewable later, by the client's own team or by an auditor, and says when it should be revisited.

## The template

| Field           | What goes in it                                                                              |
| --------------- | -------------------------------------------------------------------------------------------- |
| Title           | A short noun phrase: "Serving engine for the invoice pipeline"                               |
| Status          | Proposed, accepted, or superseded (with a link to the record that replaced it)               |
| Date            | When the status last changed                                                                 |
| Context         | The forces at play: requirements, constraints, measurements                                  |
| Options         | Each option considered, with its main trade-off                                              |
| Decision        | What was chosen, in one or two sentences                                                     |
| Consequences    | What becomes easier, what becomes harder, what is now required                               |
| When to revisit | A condition or a date: "if concurrency doubles", "when the licence changes", "in six months" |

## An example record

Illustrative example. This explains a technique; it does not describe any client system.

**Title:** Vector search for the policy knowledge system
**Status:** Accepted · **Date:** 2026-11-07

**Context:** About 400,000 passages. Documents already stored in PostgreSQL with their access-control lists. Permission filters are moderately selective (a typical user can see about a third of the corpus). Target p95 retrieval latency under 200 ms.

**Options:**

- pgvector in the existing database: one system, transactional updates, permissions in the same query. Needs iterative index scans for selective filters.
- A dedicated vector engine: filtering inside the index search and independent scaling. A second system to run, and permissions to keep in sync.

**Decision:** pgvector with HNSW and iterative scans, measured on the client's own permission data.

**Consequences:** One fewer system to operate. Recall under filtering must be monitored. Moving to a dedicated engine later means re-indexing but no application change, because retrieval sits behind its own interface.

**When to revisit:** If the corpus passes a few million passages, or p95 latency exceeds the target in production.

## Why records rather than a design document

A design document describes the system as intended at one moment. Decision records accumulate: they show how the system got to its current shape, which is what a new engineer or an auditor needs. The format follows the widely used architecture decision record convention.

## Sources

- [Architecture decision records (adr.github.io)](https://adr.github.io/)

## Contact

solutions@alesanalytics.com, or https://www.alesanalytics.com/contact.

- Every page as Markdown: https://www.alesanalytics.com/llms.txt