Decision Records

Almirah tracks work the GenAI-native way: instead of a separate issue tracker, every architectural decision, bug fix, or enhancement proposal is a Markdown file versioned right next to the specifications it affects. The decision records live in the decisions/ folder of the project and are parsed, linked, and rendered like every other document.

Anatomy of a record

A decision record is structured by conventional sections. The core ones:

• Status — a small table listing the record’s history (Proposed, Accepted, In-Progress, Implemented), with the current status marked by a * in the first column.
• Context / Decision — the problem and the decision taken, in prose, with images welcome (diagrams live in the record’s img/ folder and are copied into the build).
• Scope — a work-breakdown table with owners, dependencies, and focused/safe effort estimates; Out of Scope states explicitly what the decision does not include.
• Consequences and Alternatives Considered — the classic ADR sections.
• Affected Documents — the traceable heart of the record: a controlled table where each row states a proposed requirement text and links it up with the > notation.
• Software Versions and Review Evidences — which release the decision targets, and links to the review artifacts.

Affected documents, resolved and proposed

The “Affected Documents” table is what ties a decision into the traceability graph. A row referencing an existing requirement resolves into a hyperlink, and the requirement gains a DR (decision record) mark in the opposite direction. A row proposing a new requirement stays visibly unresolved until that requirement is actually written — so a half-implemented decision is impossible to mistake for a finished one. See it live in the decision record demo.

The overview page

All records are collected into a rendered overview at build/decisions/overview.html — status, title, and links, a project backlog generated from plain files.

Change management with no extra tool

Because records are files, change management rides on your source control: a new decision is a branch and a pull request, review happens in your normal code-review tool, and history is git log.

Nothing about the flow is Almirah-specific — which is precisely the point. The framework’s own development is managed this way, dogfooding decision records for every feature you read about on this site.