A surprise leaves an entry

The rule

After solving something that surprised you — the cause wasn't where you expected, the obvious fix was wrong, a decision turned on a constraint you didn't know about — write the entry to disk in the same session. Not "describe what should be written." Write the file.

If nothing surprised you, write nothing. A solved problem is not, by itself, a reason to write.

The scars

Scar 1 — knowledge evaporates. Knowledge produced in a session dies when the session ends. The failure isn't dramatic; it's quiet and repetitive: a tricky cause is traced, the fix applied, everyone moves on, and six weeks later the same class of bug appears and the tracing starts from zero — because the only record was a conversation nobody can search.

Scar 2 (2026-08-11) — the rule kept firing after its consumer was removed. This rule used to read "Every solved problem leaves an entry," and justified itself by claiming that without entries "there is nothing for read-before-act to read." That justification is dead. The distillation pivot rewrote read-before-act to consult the distillate and to explicitly forbid reading raw entries. Nothing reads entries anymore. The rule went on generating the L0 pile at full rate into a layer with no reader.

The measurement that settles it: clustering found 279 of 960 entries carried a mechanism — a cause/fix/lesson worth distilling. The other ~680 were written because the rule said to write, and were never eligible to become anything. They cost tokens, review attention, and lint runs, and returned nothing. Meanwhile ~20 lessons and 8 rules carry essentially all the value the system delivers.

The generalization — the reason this is a scar and not a preference — is the same one read-before-act took: a rule that names a mechanism inherits that mechanism's limits. When the pivot moved the consumer, every rule that fed the old consumer needed re-justifying, and this one wasn't. Writing was still the habit; reading had moved on.

How to apply

1. Write at the end of the work, in the same session, while the detail is still exact. A write-up produced from memory a week later loses precisely the specifics that made it useful (the line number, the actual error text, the thing that misled you first).
2. Use the matching template — new-entry stamps schema-valid frontmatter so entries are queryable from birth.
3. Never create a duplicate. Search first; if a similar entry exists, update it instead.
4. Regenerate the index after writing (brain-index) — the index is part of the write, not a chore for later.
5. Record what didn't work, not just what did. A documented dead end is the highest-value content in any knowledge base and the least likely to get written down.

The gate — both must hold, or write nothing

Apply this before writing, not as an afterthought. The default is don't write.

1. Surprise. Did the outcome differ from what you expected going in? If you'd have predicted the cause and the fix beforehand, there is nothing here to transfer.
2. Mechanism. Can you state a cause, a fix, and a lesson that would generalize past this codebase? This is not a style preference — it is literally the eligibility test tools/distill/cluster.mjs applies. An entry without a mechanism section cannot be distilled, so it can never reach any layer an agent loads. It is write-only.

Fails either test → say what you found in chat and move on. That is a complete outcome.

Explicitly do not write an entry for:

• A trivial or obvious fix with one clear option and no reasoning worth preserving.
• Something the code, types, or git history already state plainly.
• A decision that's easily reversible and cheap to redo.
• A pure implementation detail with no transferable insight.
• A session log, status update, or "what I did today" narrative. These formed the largest clusters in the first distillation run and were bound by genre vocabulary, not shared mechanism — they are the exact residue the profile gate exists to reject.
• Anything you're writing to look thorough rather than because a future session needs it.

The budget — meta work is capped at 1:4

User decision, 2026-08-11. Brain work is capped at roughly one part brain to four parts product within a session. Scar exists to make product work faster; when maintaining it becomes the work, it has inverted its own purpose.

The session that forced this: the ask was "help me scale Mnemo." One product increment shipped, and the larger share of the session went to brain adoption, brain lessons, a brain security fix, and brain distillation. Nothing done was individually wrong — which is why a per-item judgment call can't catch it, and a ratio can.

If a session starts tilting past that ratio, say so out loud and steer back. An agent silently optimizing the knowledge base instead of the product looks identical to one doing the job.

The acceptance test

Would this let someone — including you, six months from now, with no memory of this work — understand the thing in ten minutes? If not, it isn't finished. If it needs more than ten minutes to convey one idea, it's probably two entries.