brain-ingest

name	brain-ingest
description	The process for digesting a conversation, document, or research result, classifying it, and writing it down as brain content (a root-page update or a new/updated page) through the `brain` CLI.

brain-ingest

This skill is about "turning scattered input into structured brain knowledge". The input can be a conclusion from a conversation, an external document, a piece of research, or the decisions behind a set of code changes. The goal is to land that knowledge in the right place, the right category, and the right structure — and to write it through the brain CLI so it is correct by construction.

Reach for this process not only when explicitly asked to "ingest" something. The brain is the project's persistent memory (see BRAIN.md), so trigger it proactively whenever knowledge crystallizes — a decision settled in discussion, a requirement or constraint agreed, an insight that will still matter in six months. Capture it as it surfaces rather than waiting to be told.

Every read and write below is a brain CLI subcommand (list-pages / read-page / read-root to read; create-page / update-truth / … to write). The command details and the category taxonomy live in the brain-page skill — read it before creating or modifying any page.

NEVER hand-edit any file under the brain directory. All reads and writes MUST go through the brain CLI. Manual edits are unsupported and illegitimate. There is no validator and nothing at the file layer can catch a bad manual edit; correctness is guaranteed only by going through the CLI, so a hand edit silently breaks the brain's invariants.

Process

1. Break down the input

Split the input into individual atomic knowledge points. A knowledge point = one judgment / fact / decision that stands on its own. Ignore purely procedural chatter.

2. Place each knowledge point (see "Choosing where to write" in BRAIN.md)

• Changes the project's overall positioning / architecture / stack / roadmap → rewrite the corresponding root page with brain update-root <slug> (background / architecture / flow / mindmap / stack / roadmap).
• About a specific entity (a decision / concept / person / reference / sub-project) → create or update a page.
• It's common for one knowledge point to touch both — write to both sides.

3. Decide between "create" and "update existing"

• First run brain list-pages (and brain read-page <id> on likely hits) to look for an existing page on the same topic.
• Found → update it: brain update-truth --id <id> (rewrites compiled_truth and appends a timeline entry atomically), or brain append-timeline for a new piece of evidence that doesn't change the conclusion.
• Not found → create it: read the brain-page skill, then brain create-page, then fill in the real understanding with brain update-truth.
• Avoid duplication: don't scatter one topic across multiple pages.

4. Write

• All writes go through the brain CLI — see brain-page for exact commands. Never hand-edit frontmatter or timelines.
• Root pages are rewritten wholesale via update-root; they have no timeline.
• Write the body in the user's working language; keep technical identifiers (ids, slugs, field names, paths) verbatim.
• Connect related pages explicitly with [[page-id]].

5. Verify

The write commands reindex for you, and correctness is guaranteed by construction — there is no validator to run. To optionally confirm that every [[page-id]] resolves:

node <brain-page-bundle>/bin/brain.mjs lint-links

The CLI makes "compiled_truth changed but the timeline entry was forgotten" structurally impossible; the only way to break it is a hand edit, which is why you must never make one.

Principles

• Prefer less but accurate. Only capture knowledge that still matters in six months and is hard to reconstruct from the code / git.
• Every compiled_truth rewrite carries its own timeline trace — update-truth guarantees this, keeping the chain of evidence unbroken.
• Keep the category boundaries clear — the taxonomy lives in the brain-page skill.