Decision records

Vike Trader keeps one page per architectural verdict — decisions that were investigated, concluded, and are expensive to re-litigate. The directory's own README states the failure it exists to prevent, and it is concrete: an investigation that was already run, concluded, and written down somewhere unreachable gets run a second and a third time, "because nothing in a fresh checkout says it was ever settled."

A record is not a design document. Designs and execution plans live elsewhere; this directory holds answers to questions — most of them "no", or "not this way", or "not yet" — "plus the one field that keeps a 'no' from ossifying into dogma: what would reopen it."

The shape of a record

Files are named NNNN-short-title.md, numbered in the order records are written rather than the order decisions were made — the date field carries that. Each is kept to roughly one screen.

How to read a Status line

The vocabulary is accepted, superseded by NNNN, deferred, and proposed. One of the four carries an explicit prohibition.

The record's own **Status:** line is the authority; the index table carries the second copy, and those two are the only places the word may appear. "An ungated hand copy of a word that changes on ratification" is the rot this directory is built against, so it is not restated a third time — not in a record's prose, not in the index's narrative, not in the root project instructions.

The two copies are compared as the leading word only, and that is deliberate: a record may qualify its status in prose — naming what it supersedes, or recording that a finding inside it was retracted — and the index may decorate its cell with a warning mark, without either counting as a disagreement. So read the whole line. The first word is what the gate checks; the rest is where the qualification lives, and some accepted records use it to mark themselves as the weakest in the table and say exactly how far they may be cited.

The gate, and the incident behind it

crates/vike-ops/tests/decision_index_gate.rs machine-checks the index against the records on disk, in both directions. It exists because of a specific failure: the index carried a standing warning paragraph about one record, while that record had retracted the finding in its own text, in the first sentence of its own **Status:** line. "The index was still telling a reader the opposite. Nobody noticed, because nothing compared the index to the records it indexes."

every_record_has_an_index_row catches the direction that bites a new record — the common miss, since "adding the file is the interesting work and editing the table is the afterthought." every_index_row_names_a_real_record catches the direction that bites a rename. every_index_status_matches_the_record is the leading-word comparison above, and every_record_declares_a_known_status derives its vocabulary from the README's own format table rather than copying it into a constant, "so there is one authority for it and this file cannot drift from the page it polices." Underneath sit three floor tests: both stores are keyed on the four-digit id and both used to overwrite on a collision, so a duplicate made one claimant invisible to every rule above, and which one depended on directory order.

Three things are deliberately not checked. The title cell, because it is a one-line gloss rather than a copy of the record's heading. Numbering being gapless, because parallel branches can legitimately race for the next id and "a gap is a merge artifact to fix by hand, not a CI failure." And the prose outside the table — the very paragraph that motivated the gate — because "no text rule can tell whether a narrative note about a record is still true; only a reader can." The gate catches the structural half and says so, rather than implying coverage that does not exist.

Writing one

Add a record when a decision is durable, non-obvious, and would otherwise have to be rediscovered: a proposal was declined, an approach was measured and rejected, a built thing was deliberately removed, or a rule was adopted that constrains future work. Do not add one for a routine implementation choice — that belongs in the code's own module doc, which is where this codebase documents by default.

• Cite by symbol, never by line number. Line numbers rot silently, and crates/vike-ops/tests/citation_gate.rs bans them. The README's own bullet records that it used to claim these Markdown files were not machine-checked, and that the claim was false — the gate scans every tracked .md outside its exclusion list, verified by planting a bad citation into a record and watching no_citation_pins_a_line_number redden.
• Never invent a rationale. "A record whose 'Why' was reconstructed from a plausible guess is worse than no record, because it will be trusted." Where the reasoning could not be recovered, the field says so and names what is missing. Several records carry that marker; they are honest gaps, not oversights.
• Superseding beats editing. When a verdict is reversed, write a new record and set the old one's status to superseded by NNNN. The directory's worked example is a record whose reversal "is more instructive than either decision alone."

The practice generalises the principle the rest of the gate family runs on: prose that can rot becomes a test. Decision 0007 is that rule's own record.

Related: Docs gates · Architecture · Drift gates