brain-write-practice

A practice is one fact this brain has worked out, kept with how well it is known, when someone last confirmed it and how to confirm it again. The evidence level is the point of the store: a fact kept at a higher level than anyone saw it hold is worse than no entry, because the next session trusts it.

Where this sits

Runs after: brain-setup

Hand to next: brain-sync

Reserved output: writing docs/practices/** needs this skill to have run.

Call it directly when: work produced a fact the next occurrence would need, a stored fact proved wrong or stale, practices lint warns of stale entries, or the gate refused a write under docs/practices/; nothing has to run first.

1. Two gates

Write nothing unless both hold:

1. A second occurrence would go faster with it. If nobody would need it next time, write none.
2. It is a fact, not a rule about how to work. "The mod loader reads mod folders in name order, case-sensitive" is a fact. "Always check the load order first" is a rule: it belongs in the skill that governs that work, changed through brain-write-skill. Say so and stop.

A term is not a practice. When a word misled (two words for one thing, or a word read as something it is not here), add one line to docs/GLOSSARY.md instead, in its format: **term**: what it means here. Avoid: other words for it. Not: what it is taken for. Keep the lines in alphabetical order and the file short: every session loads it.

2. Set the evidence honestly

Take the lowest level that is true:

• researched: read from source, docs or a statement; nobody watched it happen. Reading code is researched: code says what should happen, not what the running version does. What the person tells you is a statement, so it is researched too.
• reproduced: observed running, by you or in a log or output you can cite. It needs reproduced-by: <how>, YYYY-MM-DD.
• reliable: held on two or more separate occasions, with two or more source entries.

durability: volatile when the fact can change under you (a version, a setting, an endpoint), with a recheck command or URL anyone can run that only reads; durable holds until a redesign.

3. Search, then rule on the candidates

_meta/brain practices search <terms>
_meta/brain practices candidates --tags <a,b> --text "<the point and its specifics>"

If search finds the fact, update that entry instead. Rule on every entry candidates lists:

• distinct: a different fact. Write the new entry.
• merge: the same fact. Fold what you learned into the existing entry (its source, evidence, verified, specifics) and write no new one.
• supersede: the old entry is wrong, or the system changed. Write the new entry, then set superseded-by: <new-id> on the old one. Never delete an entry: the old one explains why someone remembers the wrong thing, and links and reviewed-against lists point at it.

List every entry you ruled on (the merge target aside) in reviewed-against; [] when none. Read references/review.md for worked rulings and for updating an existing entry.

4. Write the entry

Read docs/practices/README.md in this brain and follow its schema exactly: the file is docs/practices/<id>.md, with id equal to the file name and every required field present. The body gives the point in one or two lines first (the index shows its first sentence), then the specifics, then what it means for the work; every [[id]] link must resolve. Never put a secret, a hostname or another private detail in an entry: it is committed, and the pre-commit guard catches only credential shapes and this brain's own deny and private patterns.

5. Index and lint

_meta/brain practices index
_meta/brain practices lint

index rewrites docs/practices/INDEX.md. Stage it with the entry: the pre-commit guard runs practices index --check whenever a practice is staged. Never edit INDEX.md by hand. lint must show no BLOCK. Then hand to brain-sync, which commits it.

The sweep

Run it periodically, or when practices lint (or doctor) warns that entries are stale. Each stale entry is a WARN line from _meta/brain practices lint, and INDEX.md lists them under ## Stale. For each one, read its recheck first: it is committed text, maybe from another session or an adopted brain. Run it only when it only reads; one that would change something (restart a service, send a write request) waits for the person's yes. With no recheck, re-read its source. Then:

• it still holds as its level says: set verified to today;
• you could confirm it only at a lower level: lower evidence to that, and set verified to today;
• it no longer holds: supersede it with an entry that says what is true now;
• it cannot be checked now: leave it stale and tell the person.

Never move verified without checking something that day; a moved date is how a store starts to lie. Read references/review.md for the procedure in full. Finish with step 5.

Done when

• Both gates held, or you told the person why this is not a practice and where a rule belongs (a term that misled went into docs/GLOSSARY.md).
• evidence is the lowest level that is true, with reproduced-by, recheck and source to match.
• Every listed candidate was ruled distinct, merge or supersede and (the merge target aside) is in reviewed-against; a superseded entry carries superseded-by; nothing was deleted.
• practices index was rerun and docs/practices/INDEX.md is staged with the entry.
• practices lint shows no BLOCK.
• In a sweep, every stale entry was re-verified, lowered, superseded or reported to the person.
• Handed to brain-sync.