jeffryandClaude Opus 5
26f8b98dc6
Four documents used the word and none defined it. cart.md leaned on it hardest — an authority claim entering as a venue fact carries a reason and can be shown wrong — which is a real mechanism resting on an undefined term. It is bedrock's because venues/ is one of the directories starting.md already lists beside published/ and gaps/. A concept named in the primitives was being half-defined in a downstream convention's four-line aside, which is the same diagnosis loom-cli made about publication two days ago. Second instance of that shape. Nothing is invented: entry 6 settled this on 2026-09-05 and the table is that entry's. New here is that a venue file is local because it has no upstream, and that it goes stale in a way no fetch can detect — so it needs the reason underneath the choice or it cannot be checked at all. Entry 84. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
3.7 KiB
Venues
.loom/venues/<name>.md — a choice you made about something that has no
document of its own to hang it on.
Kafka. React. HTTP. The organisation you work for. Things that constrain what you build without ever being invoked, and without publishing anything at you that you could adopt.
Venue and external are two questions, not two kinds of thing
external is who published it. venue is whether you had to decide
anything about it. They are orthogonal. A thing may be both, either, or
neither.
| published at us | we recorded a choice | files | |
|---|---|---|---|
| Kafka, React, HTTP | yes, by the world | yes — protobuf for schema | venue only |
| a service another team owns | yes, by them | not yet — the use is in the code | external only |
| a cluster your own org publishes | yes | yes | both |
| a library you use exactly as documented | yes | no | neither |
Both files are governed by the same rule, applied to two different ambients:
An external entry exists when the reader cannot be assumed to know the thing. A venue file exists when you made a choice worth recording.
Nobody needs telling what Kafka is, so there is no external entry — but "we use protobuf for schema" is a choice, so there is a venue file. Nobody outside can know what your internal API is for, so there is an external entry — and until using it requires an exception or a preference, there is nothing to accommodate and no venue file, because the actual use is in the code.
This is why sorting things into two bins does not work and people keep trying. The bins were never the problem. The question was.
A venue file is an account of your own decisions
Which is what makes it local by construction. An external is a copy of somebody's document and could in principle be centralised. A venue file has no upstream — there is nobody to reconcile with, because the only party who decided anything was you.
So it does not go stale the way a copy does. It goes stale when you change your mind and do not say so, which no fetch will ever detect.
A venue file that carries no delta should not exist. If you use the thing exactly as documented, write nothing. Recording the adoption is ceremony.
If there is a document, hang the choice on the document
Put a choice where reconciliation will look for it. When the thing you
decided about publishes something you have adopted, the choice belongs in the
.usages.md beside that copy and not in a venue file — because that is the
file somebody opens when the document moves, and a venue file is not.
The venue file is for what is left: the constraints of a thing that publishes nothing you can hold.
A venue is where an authority claim belongs
Because a venue fact carries a reason and can therefore be shown wrong.
The alternative is worse and common: somebody with authority enters a conversation as a voice, and "we do it this way" arrives with no reason attached and nothing that could contradict it. Written as a venue constraint, the same instruction becomes a claim about the world, and a claim about the world is something a later reader can discover was false.
Checking it is still true
Nobody will tell you. There is no publisher to ask, no ETag, and no
conditional request that will ever come back 200.
So a venue file needs what a published document needs: a date, and the reason underneath the choice. The reason is the whole of it — "we use protobuf for schema" is unfalsifiable a year later; "we use protobuf because the consumers are in three languages and JSON schema drift was costing us a release a quarter" can be checked against a world that may have changed.