/gaia-brain-health

user-facing
Category:
Sprint Management
Lifecycle phase:
4 -- Implementation
Arguments:
none

What it does

/gaia-brain-health shows a read-only health view over the brain knowledge layer: it lists every indexed artifact that carries no governance link -- a traceability gap. A gap is a quality signal, never a failure, so this view always succeeds even when unlinked nodes are present. It is the human-facing payoff of the knowledge layer's coverage check: it makes missing traceability visible to browse on demand, without a statusline nag.

When to use it

  • You want a quick read on which artifacts have no traceability before a sprint review.
  • You made a burst of artifact edits and want to confirm nothing slipped through without a governance link.
  • You are browsing the knowledge layer and want to find coverage gaps to close.

Prerequisites

  • A built knowledge index. The view consumes the index produced by /gaia-brain-reindex. If the index does not exist yet, the view says so and points you to build it first -- and still exits cleanly.

How to invoke

/gaia-brain-health

What it does step by step

  1. Read the index Loads every entry from the committed knowledge index.
  2. Re-derive the linked verdict For each entry, recomputes whether the artifact is linked using the four-source linked predicate: its frontmatter traces-to declaration, its frontmatter epic, an allocation row in the epics registry, or a mapping in the traceability matrix.
  3. Collect the gaps An artifact with none of the four is unlinked. It is collected, never dropped or treated as an error.
  4. Report Prints the unlinked nodes in a stable, sorted order with a count, then exits cleanly.

Reading the output

A node listed here carries no governance link of any kind. The remedy for story-shaped artifacts is to add traceability -- a traces_to or epic entry in the artifact's frontmatter, an allocation row in the epics registry, or a matrix mapping -- not to suppress the signal. An empty list means every indexed artifact is linked.

Many unlinked entries are expected and normal. The linked predicate is meaningful for story files -- the artifacts that should trace to a requirement, an epic, or a test. Non-story artifacts such as meeting notes, action items, brainstorm outputs, retrospectives, and architecture-decision shards legitimately have no governance edges. Their presence in the unlinked list is not a problem to fix. Focus on unlinked stories when looking for gaps to close.

Read-only boundary

The health view is purely read-only: it reads the index and the existing governance data and writes nothing. The unlinked verdict is recomputed from the linked predicate on every run, so its answer can never drift from the predicate and needs no change to the index format.

Outputs

OutputLocationDescription
Health reportprinted to the consoleThe sorted list of unlinked nodes with a count. Nothing is written to disk -- the view is read-only.

What to run next

  • /gaia-brain-reindex -- rebuilds the index (and its map of content) so the health view reads the current filesystem.

Troubleshooting

It says there is no index

Run /gaia-brain-reindex to build the index, then re-run the health view.

A node I expect to be linked is listed

The view re-derives links from frontmatter, the epics registry, and the traceability matrix. If a node should be linked, add a traces_to or epic entry to its frontmatter, an allocation row in the epics registry, or a matrix mapping, then rebuild the index and re-run.