/gaia-brain-query

user-facing
Category:
Sprint Management
Lifecycle phase:
4 -- Implementation
Arguments:
<story-key> plus an optional mode flag (--envelope, --health, or --search <terms>)

What it does

/gaia-brain-query is a read-only traversal over the brain knowledge layer. From a seed story key it walks the knowledge index's typed governance edges and returns the story's governance envelope -- every related artifact grouped by direction -- in a single invocation. It is the read counterpart to the reindex sweep (which is the sole writer of the index): the query writes nothing.

Today this command is manual and opt-in -- users and agents invoke it explicitly. Automatic mandatory consultation by agents is a planned future feature, not yet shipped.

When to use it

  • You want to see, for one story, the requirements and decisions that govern it, the tests and reviews that gate it, and the design that sits alongside it -- all at once.
  • You are reviewing a story and want a quick read on its governance coverage.
  • You want to search the indexed synopses for a phrase, or browse the unlinked-node health view, from the same entry point.

Prerequisites

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

How to invoke

/gaia-brain-query <story-key>                 # the governance envelope (default)
/gaia-brain-query <story-key> --envelope      # explicit
/gaia-brain-query --health                    # the unlinked-node view
/gaia-brain-query --search "<terms>"          # synopsis substring search

The governance envelope

For a seed story, the envelope groups the related nodes into three directions:

  • UP -- the governance chain above the story: the requirements it implements, the decisions that govern it, and its parent epic. UP is a bounded transitive walk -- it follows the story up to its epic and the requirements and decisions that govern it, with a depth cap and a cycle guard so the walk always terminates. The walk follows only the parent epic; it never descends into sibling sub-stories.
  • DOWN -- the artifacts below the story: the tests that verify it and the reviews that gated it. DOWN is a single hop from the seed.
  • LATERAL -- the design artifacts that sit alongside the story. LATERAL is a single hop from the seed.

The output is deterministic -- grouped by direction, then ordered by a stable edge-type rank, then by target -- so two runs over the same index produce byte-identical output. The format is plain, grep-able structured text.

What it does step by step

  1. Read the index Loads every entry and its typed edges from the committed knowledge index.
  2. Resolve the seed Looks up the seed story. An unknown key is reported as an unresolved reference, never an error.
  3. Walk the envelope Follows the UP governance chain transitively (parent epic, requirements, decisions) with a depth cap and cycle guard, and collects the DOWN and LATERAL edges a single hop from the seed.
  4. Check freshness Recomputes the content hash of each surfaced node's canonical file and compares it to the indexed hash; a drifted or missing file is flagged stale with its path.
  5. Render Prints the envelope grouped by direction in a stable, sorted order, then exits cleanly.

Read-time freshness

When the query surfaces a node's synopsis, it recomputes the content hash of the node's canonical file and compares it to the hash the index stamped at index time. If the file has changed since the last reindex, or is missing, the node is marked stale and the query surfaces the canonical path so you can read the current bytes directly -- the possibly-out-of-date stored synopsis is never served as if it were current. The query surfaces the path, never the file contents, so its output stays bounded regardless of file size. A stale node is a prompt to rerun the reindex sweep; it is never an error.

Graceful degradation

The query never fails on a partial graph. A node with no edges in a direction renders a non-error (no … edges) line for that direction; an unknown key is reported as unresolved and still exits cleanly; a missing index prints an explanatory line pointing you to rebuild it, and still exits cleanly.

Read-only boundary

The query reads the knowledge index and the artifact and state roots (the latter only to recompute a canonical file's content hash for the freshness check). It never reads or writes the agent-sidecar memory tree. The boundary holds in both directions: the ground-truth refresh likewise never reads the knowledge index. Retrieval is grep, tags, and the index only -- there is no vector database, embedding model, or external search dependency anywhere in this layer.

Outputs

OutputLocationDescription
Governance envelopeprinted to the consoleThe seed node, its freshness state, and the UP / DOWN / LATERAL groups in a stable, sorted order. Nothing is written to disk -- the query is read-only.

What to run next

Troubleshooting

It says there is no index

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

A node is marked stale

The node's canonical file changed since the last reindex. Read the surfaced path for the current content, or run /gaia-brain-reindex to refresh the index.

A key is reported as unresolved

The key is not in the index. Confirm the key spelling, and run /gaia-brain-reindex if the artifact is new.