A specimen is pressed once, labelled, and shelved where it can be found. The same plant is not pressed twice. A document is a specimen: one house, one label, and every other document that needs it points at the shelf.
This file owns the pattern. The houses a project keeps, the levers for writing a document an agent will run, and the CLI are in references/houses.md.
The rule
One house per fact; pointers, not copies. Before writing a sentence,
ask where that fact already lives. If it lives somewhere, link there. If
it lives nowhere, put it in the house the reference names for its kind
and link from where you are. A fact restated in a second file is a fact
that will be wrong the next time its home changes; check counts those.
Write
- Name the kind. The reference lists the eleven kinds and the house each one has. A document that is two kinds is two documents.
- Front-load the leading word and the one defining constraint. A reader, human or agent, decides in the first line whether to keep reading; the pointer to this document, wherever it sits, uses the same word.
- Keep steps and reference apart. Steps in order, each ending on a criterion a reader can check: done or not done, with a number where one exists. Reference consulted on demand goes below the steps or behind a pointer; what only some readers need goes behind a pointer.
- Let the environment speak. A command's
--help, a config file, a directory listing are sources of truth. Write down the convention that is not in them and the reason behind a choice; leave the lookups where they cannot go stale. - Say the positive. State the behaviour wanted; a prohibition earns a line only as a hard guardrail, paired with the positive it protects.
- Prune. Every line either changes what the reader does or leaves. Layers that settled because adding felt safe are sediment; core through them.
Check
de-novo skills herbarium check # links n/n · copies n · language n · pages n/n · archive n
Run it before a document lands, and let CI run it on every change. A broken link, a copied sentence, a public surface in another script, or a page over its cap is a non-zero exit. Links from active documents into the archive are shown, not judged: a person decides whether the pointer is a citation or a leftover.
Retire
A design that is no longer operating authority moves to the archive with its date and a link to what replaced it. Active instructions do not lean on it. It is not deleted: a reader who finds an old decision should be able to read why it was made.
Invariants — not weakenable
- One house per fact. A second copy is a defect the check counts.
- The CLI never edits. It counts; a person or an agent moves the text.
- Public surfaces are one language, the one the values file names.
- A human page is short. Its prose stays under the cap; a diagram in a fence is looked at, not read, and does not count.
- Retired documents are kept, dated, and pointed at what replaced them.
Not this skill
- Deciding what is true. Mycelium holds facts; this holds the documents that point at them.
- Writing the record of a sprint. Understory does that, under this rule.
- A documentation site, a publishing pipeline, a translation workflow.