# Our decisions file is a history, not a spec

Principles · October 22, 2026 · Henry Kobutra with Codex

Looking back at September 16, 2026.

![Layered ivory and blue contour ribbons form an archive of pages, with one short orange current plane above them.](/log/images/our-decisions-file-is-a-history-not-a-spec/cover.webp)

By September 16, Hydrant's decisions file had become valuable and awkward. It held accepted choices, rejected alternatives, later amendments and the reasons behind them. Asking every agent to read it from top to bottom made a careful process slower without making the next task clearer.

We gave the file a narrower job: history.

## Start with what is true now

A short current-decisions page is now the entry point. It names the rules that affect work today and links to the history behind them. An agent working on settings can find the current structure and the relevant visual decision. An agent changing release infrastructure can jump to the evidence rules and their rationale.

The longer history stays intact. Approved choices record who decided, why, which work they affected and what followed. When a later decision replaces an earlier one, the old entry is labelled as superseded instead of being polished out of existence. Rejected specimens remain useful because they explain why a technically valid direction was not accepted.

The summary does not get to overrule that evidence. If a task touches a domain with a decision, the agent searches the history, reads the matching section and follows later amendments. A conflict is a reason to inspect the source, not an invitation to pick the shorter file.

## Read once, then read what changed

The same idea applies to an issue. At the start of a work attempt, the agent reads the complete issue activity and records a compact checkpoint: the scope, owner, decisions, last activity position, code revision, checks and evidence locations. Later it asks for activity after that position.

That avoids rereading the same history through every stage. It also avoids a more dangerous shortcut. A summary can help someone resume; it cannot replace missing source evidence when a decision or permission matters.

The change was shipped as workflow infrastructure, with no claim that it had already saved a measured number of tokens or minutes. The point was simpler: current instructions should be quick to find, and history should remain honest.

A spec tells you what to build now. A decision history tells you how the present became defensible. We need both, and they are easier to use once they stop pretending to be the same document.

Contact: bots@hydrant.dev