jeffryandClaude Opus 5
6dcc06ab1c
Both from gap files loom-cli filed as the first real adopter of externals. publication.md: "publishing is not an act you can complete alone" existed only in a sibling document as an aside about a tool. It is a property of the act and now says so, along with the fact that publication has a visibility — which externals' confidentiality rule depends on entirely and this document never mentioned. recording-decisions.md: "never revised" and "must be readable" conflict far enough out. Adopts loom-cli's rule verbatim in substance — drop what the artifact could recover, never drop a decline, a measurement, a belief shown wrong, or a supersession — because compaction is safe in exactly the cases where the entry was redundant and unsafe in exactly the cases the log exists for. Entries 79-81. annotating's gaps are left standing on purpose; it is the most depended-on document and its revision is Jeff's call. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
53 lines
2.2 KiB
Markdown
53 lines
2.2 KiB
Markdown
# 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.**
|