/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`). The stdin body must start with an authored `# Title` and include real content after that heading. A missing slot is created by that write.
• About a specific entity (a decision / concept / person / organization / 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. Start the body with `# Title`. An older root page whose stored body has no H1 may omit that heading on its next write; the stored frontmatter title is inserted.
• Write the body in the user's working language; keep technical identifiers (ids, slugs, field names, paths) verbatim. Pass `--summary` in that same language on `create-page` and `update-truth` (the creation entry included). The CLI will not insert an English timeline sentence for you.
• 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.