Every note here carries one of four labels. They describe how settled the contents are, not how much work went in.
The four states
Reagent
Raw. Gathered before I understood it. Most notes start here and a lot of them stay here, which is fine: an unprocessed note still says what caught my attention and when.
Tincture
Steeping. I have come back to it at least once and changed something. This is where most of the actual thinking is visible, because it is the only state where the note is still moving.
Elixir
Stable. I can explain it without looking, and it has survived being used for something real. Rare, and slower to arrive than I expect every single time.
Failed batch
Wrong, kept on purpose, labelled with what went wrong.
How a note moves
The transitions are deliberately mechanical, so there is no judgement call to avoid on a bad day.
Reagent to tincture: I came back and changed it. That is the whole test. Not “it got better”, just that a second pass happened. Revisiting is the promotion.
Tincture to elixir: I can explain it cold, and I have used it. Both halves matter. Explaining without notes rules out memorised phrasing hiding a gap, and having used it rules out understanding that only holds in the abstract. If either fails, it stays a tincture. There is no deadline on that.
Anything to failed batch: the content turned out to be wrong.
What a failed batch actually is
This is the part worth being precise about, because the obvious reading is the wrong one.
A failed batch is a wrong conclusion, not a stalled effort.
It is a note that said something, and that something was not true. I thought the bug was in the proxy, it was in the DNS. I thought this pattern was the right shape, it collapsed under a case I had not considered. That is real information, it is expensive to recover once forgotten, and it is worth more six months later than silence.
What it is not:
- Not a project I stopped working on.
- Not something unfinished.
- Not losing interest.
- Not a gap between when I said I would do a thing and when I did.
Something I put down is a reagent that stopped steeping. It keeps its label, it sits on the shelf, and it is available if it ever gets picked up again. Nothing about it is a failure and nothing here marks it as one. That distinction is the whole reason this vocabulary is worth having: an apothecary has a word for a batch that came out wrong, and no word at all for a jar nobody has opened lately, which is exactly the right pair of facts.
The other thing a failed batch is not: deleted. When something is corrected, the wrong version stays visible with the correction next to it rather than being quietly rewritten. Same rule I built into the Crawler’s Companion for the same reason: what I believed earlier is part of the record, and a shelf where every label was always right is a shelf that is lying.
Building something up
Notes accumulate before they combine, not the other way round.
Several reagents on one subject eventually make it obvious that they are about the same thing. That is when a tincture gets written: not a summary of the reagents, but the thing they turned out to be evidence for. The reagents stay. They are the working, and the working is often more useful than the answer.
A tincture that stops changing across a few visits has become an elixir, whether or not it feels finished. Feeling finished is not one of the criteria, because by that measure nothing ever would be.
Structure comes from links, not folders. If two notes reference each other, the graph shows it, and the shape of a subject emerges from what actually connects rather than from a hierarchy I guessed at up front.
The mechanics
A published knowledge note carries one state tag and at least one subject tag in frontmatter alongside publish: true. The state says how settled it is, the subject says what shelf it belongs on. Changing state means changing that one word. Git keeps every prior version, so the history of a note’s confidence is recoverable without cluttering the note with it.
Navigation pages are exempt. The site front page and a section’s routing-only index.md describe the shelves rather than contributing a knowledge claim, so assigning them a maturity state would be false metadata.
Nothing is published without publish: true. That is opt-in on purpose: a
forgotten flag means a note is missing, never that something private is public.