/gaia-brain-reindex

What it does

/gaia-brain-reindex rebuilds the brain knowledge layer's index from source. It is the sole writer of that index: it walks the project's artifact and state trees, derives a typed-edge graph of how the artifacts relate, stamps every entry with a content-integrity hash, and writes the index atomically. Because every run regenerates the whole index from the files on disk, hand-tampering never persists and synopses never silently drift.

When to use it

• You made a burst of mid-sprint artifact edits and want the knowledge index refreshed before querying it.
• You want to confirm the index matches the current filesystem after a reorganization.
• You normally do not need to run it by hand -- the sprint-close ceremony runs it automatically as a best-effort pass.

Prerequisites

• No strict prerequisites. If the knowledge store does not exist, it is created automatically.

How to invoke

/gaia-brain-reindex

What it does step by step

1. Walk the source roots Enumerates every artifact under the artifacts and state trees. Three story-file layouts are all discovered and tolerated; a story present in more than one layout de-dupes to the highest-precedence layout.
2. Hash each file Computes a content hash for every discovered file.
3. Short-circuit unchanged files If the existing index already carries that exact hash for a file, the prior synopsis and edges are carried forward unchanged -- no re-work. This makes a re-run fast: the first sweep does the full work; later sweeps only touch what changed.
4. Generate synopsis + harvest edges For new or changed files, generates a deterministic one-paragraph synopsis (first heading plus first prose line) and harvests the artifact's typed governance edges from the project's existing planning data.
5. Stage atomically Writes the whole index to a sibling temporary file next to the live index, validates it against the index schema, and only then renames it into place. A concurrent reader never sees a partial index.
6. Fail safe If validation fails, the previous index is left exactly as it was and the run reports the failure.
7. Render the map of content After the index is committed, the sweep renders a human-browsable map of content beside it. This render is a pure function of the index and best-effort -- a render failure is logged and the sweep still succeeds, because the index is the single source of truth and the map is a derived convenience.

Read-only boundary

The sweep reads from exactly two trees -- the artifacts tree and the state tree -- and writes to exactly one: the knowledge store. It is a read-only consumer of everything it indexes; it never modifies an artifact and never copies an artifact's bytes into the knowledge store. Entries point at each file in place.

The sweep does not read or write the agent-sidecar working-memory tree. Those sidecars are private, per-agent working memory maintained by a separate ground-truth refresh flow; the brain index is a distinct, project-wide governance index. The two are independent subsystems and neither substitutes for the other.

Outputs

What to run next

• /gaia-sprint-close -- closes the sprint and runs a best-effort reindex automatically before emitting the close event.

Troubleshooting

Reindex reported a failure at sprint-close

The sprint-close reindex is best-effort and non-blocking -- a failure warns and the sprint still closes. Run /gaia-brain-reindex on demand to retry and surface the error directly.

The index looks out of date

Run /gaia-brain-reindex to rebuild it from the current filesystem. Every run regenerates the whole index, so it always matches the files on disk afterward.

Related commands

For a full explanation of the knowledge layer, edge types, and the linked predicate, see the GAIA Brain concept page.