/gaia-unfeed

user-facing
Category:
Sprint Management
Lifecycle phase:
4 -- Implementation
Arguments:
<slug>

What it does

/gaia-unfeed removes an ingested document from the brain knowledge layer. It is the inverse of /gaia-feed: where /gaia-feed writes a provenance-stamped file and registers a brain-index entry, /gaia-unfeed deletes both atomically.

This is the sanctioned way to remove an ingested source. Do not hand-edit the knowledge files directly.

When to use it

  • You ingested a document you no longer need in the knowledge layer (wrong source, outdated version, duplicate).
  • You want to stop using a previously ingested reference and remove it from brain queries.
  • You want to clean up a stale or failed ingestion that will never be refreshed.

Prerequisites

  • A valid brain index must exist. The command reads brain-index.yaml to locate and de-register the entry.
  • The slug must correspond to a previously ingested document. If the slug does not exist, the command is a no-op.

How to invoke

/gaia-unfeed my-api-docs

Pass the slug of the ingested document to remove. This is the same slug shown in the ingested file's frontmatter and in the brain-index entry key.

What it does step by step

  1. Validate the slug Confirms the slug is well-formed and does not contain path traversal sequences. Rejects any slug that would escape the .gaia/knowledge/ingested/ namespace.
  2. Locate the entry Looks up the slug in brain-index.yaml among source_type: ingested entries. Only ingested entries can be removed -- project-artifact entries are never touched.
  3. Delete the ingested file Removes .gaia/knowledge/ingested/<slug>.md from disk.
  4. De-register the index entry Removes the matching entry from brain-index.yaml. The index is validated before committing; on failure the prior index is preserved.
  5. Re-render the human index Updates brain-index.md (the human-readable Map of Content) to reflect the removal.

Safety guarantees

  • Idempotent. If the slug is not present in the brain index, the command exits cleanly as a no-op. Running it twice has the same effect as running it once.
  • Ingested entries only. The command only ever removes entries with source_type: ingested. Project-artifact entries (stories, architecture decisions, epics, etc.) are never modified or deleted.
  • Slug containment. The slug is sanitised and a path containment check ensures the delete target is inside .gaia/knowledge/ingested/. Traversal attempts are rejected.
  • Atomic index update. The brain-index is written to a temporary file, validated, and renamed into place. A failed validation preserves the prior index unchanged.

Outputs

OutputLocationDescription
Deleted ingested file.gaia/knowledge/ingested/<slug>.mdRemoved from disk.
Updated brain index.gaia/knowledge/brain-index.yamlThe matching ingested entry is removed.
Updated human index.gaia/knowledge/brain-index.mdRe-rendered to reflect the removal.

What to run next

  • /gaia-brain-query -- verify the removed document no longer appears in brain queries.
  • /gaia-feed -- ingest a replacement document if needed.

Troubleshooting

The slug is not found

The command exits cleanly as a no-op. Verify the slug matches what is in the brain index (check brain-index.yaml or the file under .gaia/knowledge/ingested/).

Brain-index validation failed

The updated index did not pass schema validation after removing the entry. The prior index is preserved unchanged. Check the error message for details.

How do I update a source instead of removing it?

Use /gaia-feed with the same --slug. The existing entry is overwritten cleanly without needing to unfeed first. See the same-slug overwrite behavior documentation.