dira decision memory for AI coding agents
$dira whydec-0009
int-0001The why of a decision survives the session that made itactive 2026-07-29
dec-0009ADRs are mirrored exhaust; the ledger entry is the recordaccepted 2026-07-29
✗ Keep ADRs as the source of truth; dira only indexes themMarkdown prose cannot carry the typed fields the rest of the design needs — alternatives with why_nots, typed edges, lifecycle state, namespaced parent refs. `dira check` and `dira map` both become impossible, and dira degrades to full-text search over the pile it exists to replace.
✗ Drop ADRs entirely once dira is adoptedADRs are the readable-without-tooling artifact and the one an outside contributor or auditor expects to find in docs/adr/.
✗ Bidirectional sync — edit either the ADR or the entry, reconcile bothTwo writable representations of one fact is a conflict generator with no correct resolution rule.
int-0001The why of a decision survives the session that made it
dec-0009ADRs are mirrored exhaust; the ledger entry is the record
✗Keep ADRs as the source of truth; dira only indexes them
✗Drop ADRs entirely once dira is adopted
✗Bidirectional sync — edit either the ADR or the entry, reconcile both
dec-0009 ◆ accepted 2026-07-29

Arising from int-0001 — The why of a decision survives the session that made it

ADRs are mirrored exhaust; the ledger entry is the record

When `mirror.adr = true`, accepting a decision writes two artifacts from one capture: the entry at `.dira/entries/dec-NNNN.md`, and a conventional ADR at `docs/adr/NNNN-slug.md` following the host repo's existing convention (kazi's is `docs/adr/NNNN-slug.md`, currently 83 numbered).

The direction of authority is strictly one-way:

- The **entry** is the record. It is what `dira why`, `dira map`, and `dira check` read, and the only thing that is queryable. - The **ADR** is exhaust — generated, human-readable, expected by convention, and safe to delete. Deleting every ADR must lose no information. - Edits to an ADR are **not** read back. If someone edits an ADR by hand, dira regenerates over it and says so. The fix is to edit the entry.

This is the honest resolution of the original complaint. The ADRs were never the problem; not reading them was, and that is unfixable at the ADR layer because files are pull-based. So the files keep existing for the humans and audits that want them, and the retrieval path moves entirely to push — `dira brief` at session start, `dira why` on demand. Nobody has to open either file for the system to work.

One number worth remembering as the test of this decision: kazi has 83 ADRs and the person who wrote them does not re-read them. If dira ever requires reading a file to function, it has reproduced that outcome with more machinery.

Alternatives on record — 3

✗Keep ADRs as the source of truth; dira only indexes themrefused Markdown prose cannot carry the typed fields the rest of the design needs — alternatives with why_nots, typed edges, lifecycle state, namespaced parent refs. `dira check` and `dira map` both become impossible, and dira degrades to full-text search over the pile it exists to replace.

Markdown prose cannot carry the typed fields the rest of the design needs — alternatives with why_nots, typed edges, lifecycle state, namespaced parent refs. `dira check` and `dira map` both become impossible, and dira degrades to full-text search over the pile it exists to replace.

revisit ifnever for new entries; indexing remains the right answer for a legacy corpus (qst-0003)

✗Drop ADRs entirely once dira is adoptedrefused ADRs are the readable-without-tooling artifact and the one an outside contributor or auditor expects to find in docs/adr/.

Deleting them makes the record hostage to dira being installed, which contradicts the plain-text durability that dec-0002 deliberately bought. The corpus is also 83 ADRs deep in kazi — throwing it away is not a migration, it is a loss.

✗Bidirectional sync — edit either the ADR or the entry, reconcile bothrefused Two writable representations of one fact is a conflict generator with no correct resolution rule.

The whole reason status is derived rather than stored (dec-0004) is the same reason applied to a different field.

Every decision in this repo is recorded like this one.

Keep your own →