dira decision memory for AI coding agents
$dira whynote-0001
note-0001Two fidelity gaps found by running `dira why` against the real ledgeractive 2026-07-30
note-0001Two fidelity gaps found by running `dira why` against the real ledger
note-0001 ◆ active 2026-07-30

Two fidelity gaps found by running `dira why` against the real ledger

Building E1's `dira why` and pointing it at this repo's own ledger surfaced two gaps that no test caught, because in both cases the artifact under test agreed with itself.

1. Multi-word queries only match as a contiguous substring

`dira why "read time"` resolves. `dira why "status derived"` finds nothing, even though both words are in `dec-0004`'s title — they are simply not adjacent in that order. The resolver runs `instr(lower(title), ?)`, so word order and adjacency are load-bearing.

`dec-0014` chose *lexical* matching over embeddings, deliberately. Substring is narrower than lexical, and the difference lands on exactly the person who matters most: the stranger who types the question in their own words, not the author's. "why postgres instead of mysql" fails against a title reading "MySQL, not Postgres, for the metrics store".

The fix stays inside `dec-0014` — require all query tokens to be present, rank contiguous matches first so today's top result never moves. No embeddings, no new dependency.

2. The design mockup shows an alternative the data model has no room for

`docs/design/screens/s1-decision.html` renders `dec-0001` with "Alternatives on record — 4": one upheld (`✓ Go`) and three refused. The real `dec-0001` records **four refused** alternatives and no upheld one. In this schema the chosen option *is* the decision title — `alternatives` holds only what was ruled out.

So the mockup shows a row the renderer cannot produce, and gets the count right for the wrong reason. It is a defensible **design proposal** — synthesising an upheld row from the title would make the page read better for a stranger — but it is currently presented as a rendering of real data and is not one.

Either the schema gains a way to mark the upheld option, or the mockup drops the row. Not a judgement call to make here; it is E6's, and this is its first concrete test case.

The pattern, again

This is the fifth instance this month of the same shape: **a check that validates a declaration rather than a rendered result.** The mockup was reviewed against the design laws and passed. The resolver was tested against queries its author wrote, in its author's word order. Neither was ever run against the other's reality until a reader existed. `qst-0006` records the model-level version of the same discovery.

Alternatives on record — 0

no alternatives recorded on this entry

Every decision in this repo is recorded like this one.

Keep your own →