/gaia-discover

user-facing
Category:
Discovery & Research
Lifecycle phase:
Pre-backlog (upstream of Phase 1)
Arguments:
<gesture> [args]

What it does

/gaia-discover manages the Discovery Board -- a pre-backlog staging area where ideas are captured, researched, evaluated, prioritized, and graduated into the formal GAIA lifecycle. Every mutating gesture routes through a single sanctioned writer script, ensuring consistent state management.

Lifecycle positioning

Discovery is a pre-backlog lifecycle stage that sits strictly upstream of /gaia-add-feature. Ideas flow through the Discovery Board pipeline before entering the formal GAIA lifecycle: 

Captured --> Researching --> Evaluated --> Graduated --> /gaia-add-feature

The only downstream edge from Discovery into the formal backlog is graduate, which bridges a validated idea into /gaia-add-feature --from-discovery. Discovery does not replace Phase 1 (Analysis). It is an informal staging area where ideas are captured and evaluated before they become formal change requests.

When to use it

  • You have a raw idea, user request, or observation that is not yet ready for /gaia-add-feature.
  • You want to track and prioritize pre-backlog ideas without committing them to the formal planning pipeline.
  • You need a lightweight capture workflow with no validation gates or subagent overhead.

If the idea is already validated and ready for implementation, skip Discovery and go directly to /gaia-add-feature.

Prerequisites

A GAIA project must be initialized (/gaia-init or /gaia-brownfield completed). The Discovery Board file is created automatically on first capture.

How to invoke

/gaia-discover capture "Add dark mode support" --source "user-feedback"

Each gesture has its own syntax -- see the table below.

Gestures

GestureDescriptionMutates?
captureCapture a new idea with a title and source tag.Yes
boardView the board with optional --horizon and --priority filters.No
researchAdvance an item to the Researching state.Yes
evaluateAdvance an item to the Evaluated state.Yes
graduateGraduate an item, bridging it to /gaia-add-feature.Yes
parkPark an item for later consideration.Yes
reviveRevive a parked item to its previous state.Yes
prioritizeSet priority and horizon for an item.Yes

Inputs

InputSourceDescription
Gesture First argument The operation to perform (capture, board, research, etc.).
Title / flags Subsequent arguments Gesture-specific arguments (--title, --id, --source, --priority, --horizon).

Outputs

OutputLocationDescription
Discovery Board .gaia/state/discovery-board.yaml YAML file tracking all discovery items and their states.

Example session

> /gaia-discover capture "Add webhook retry with backoff" --source "support-ticket"

Captured: item <id>
  Title:    Add webhook retry with backoff
  Source:   support-ticket
  State:    Captured
  Priority: (unset)
  Horizon:  (unset)

> /gaia-discover board

Discovery Board
  <id>  Captured   Add webhook retry with backoff  [support-ticket]

> /gaia-discover prioritize --id <id> --priority High --horizon Now

Prioritized: <id>
  Priority: High
  Horizon:  Now

> /gaia-discover graduate --id <id>

Graduated: <id>
  Next: run /gaia-add-feature --from-discovery <id>

Operator guidance

  • Discovery synthesis is internal-only. The synthesis text, notes, and research captured on the board are private project artifacts. They must never appear verbatim in published source, user-facing documentation, or commit messages.
  • Never paste secrets into capture. The capture gesture writes its input directly to discovery-board.yaml. API keys, credentials, tokens, and any other sensitive material must never be used as the title or source tag. Sanitize inputs before capture.

What to run next