Recording decisions

An entry says what was decided, what it is believed to advance, and the belief that could turn out false.

Only a stated belief can later be shown wrong. “To satisfy §4” is a citation, not a reason — it points at a label. A constraint whose reason cannot be found gets re-litigated as a defect by whoever inherits it.

Appended, newest last, never revised. A later entry supersedes an earlier one by saying so. A revised record cannot show that anybody changed their mind, which is most of what a reader wants from it.

No status, no assignee, nothing to process. The moment an entry can be “not yet applied”, somebody must track which ones are — and the record becomes a work tracker, which is how a thing that outlives its authors turns into a queue nobody reads.

Declines belong here too

What you considered and did not do, with the reason you did not.

Almost nobody writes these, and three weeks later somebody proposes the thing you already rejected — because the rejection lived somewhere that did not survive.

Compaction, and the entries it may never touch

“Never revised” and “somebody must be able to read it” both hold, and far enough out they conflict — a log nobody can get through has stopped being a record.

Compaction is allowed. Dropping an entry is not the same as revising one, and the uncompacted log is in git history, which is where a reader who needs it goes.

An entry may be dropped when a competent reader could recover it by reading the artifact.

An entry may never be dropped when it records a decline, a measurement, a belief that was shown wrong, or one entry superseding another.

Which means compaction is safe in exactly the cases where the entry was redundant with the artifact, and unsafe in exactly the cases the log exists for. The four protected kinds are the ones with no other home: the code shows what was built and can never show what was refused, what was measured, what turned out false, or that somebody changed their mind.

A compaction is itself a decision, and gets an entry.

Where it lives

.loom/event-log.md. A stream, so a file.

This page is a copy of a document published by loom/bedrock, rendered here. The source is https://git.hypertheory-labs.dev/loom/bedrock/raw/branch/main/.loom/published/recording-decisions.md and is what the copy is checked against.