/gaia-help

user-facing
Category:
Getting Started
Lifecycle phase:
Any
Arguments:
[optional free-text description]

What it does

/gaia-help is GAIA's context-sensitive help system. It looks at what you want to do, examines which artifacts already exist in your project (PRD, architecture, sprint plan, etc.), and suggests the three to five most relevant commands to run next. Every suggestion is verified against the real list of available commands, so it will never suggest a command that does not exist.

When to use it

  • You are new to GAIA and want to know where to start.
  • You just finished a step (for example, created a PRD) and want to know what comes next in the lifecycle.
  • You have a task in mind ("I need to write code", "review my security") but are not sure which GAIA command handles it.
  • You want a quick orientation on which lifecycle phase your project is currently in.

Prerequisites

None. This command works on any project at any stage, including projects with no GAIA artifacts yet. The suggestions improve as more artifacts exist, because GAIA can better determine your lifecycle phase.

How to invoke

/gaia-help

With no argument, shows categories and a lifecycle phase summary.

/gaia-help I need to write code for a story

With a description, suggests commands that match your intent.

What it does step by step

  1. Load the command map Reads the intent-to-command map that associates natural-language intents ("I want to start a new project") with specific slash commands (/gaia-brainstorm). Also loads the authoritative list of valid commands.
  2. Parse your query If you provided a description, it matches your text against known intents. If you typed plain /gaia-help with no argument, it shows the top-level categories and lifecycle phase guide.
  3. Detect lifecycle phase Scans your docs/ directory to see which artifacts exist:
    • No artifacts -- you are in Phase 1 (Analysis).
    • PRD exists but no architecture -- Phase 2/3 (Planning).
    • Architecture exists but no sprint plan -- Phase 3/4 (Solutioning).
    • Sprint plan and stories exist -- Phase 4 (Implementation).
    • Test plans and release material exist -- Phase 5 (Deployment).
    This phase detection helps rank which commands are most relevant right now.
  4. Cross-check suggestions Every candidate command is verified against the master command list. Any command that does not exist is silently dropped. This guarantees you are never pointed to a nonexistent command.
  5. Present suggestions Shows the top 3-5 commands with a one-line description and a brief rationale explaining why each is relevant given your project's current state.
  6. Offer to activate Asks if you want to run one of the suggested commands right away. Reply with the command name to launch it, or say "no" to exit.

Inputs

Input Source Description
description Command argument (optional) Free-text description of what you want to do.
Artifact tree docs/ directories Scanned to detect which lifecycle phase the project is in.

Outputs

This command produces text output only -- it does not create or modify any files. It displays:

  • Your detected lifecycle phase.
  • 3-5 suggested commands with descriptions and rationales.
  • An offer to run one of the suggestions immediately.

Example session

With no argument (new project)

> /gaia-help

Your project appears to be in Phase 1 (Analysis) -- no planning
artifacts found yet.

Suggested next command(s):

1. /gaia-brainstorm -- Brainstorm a new project idea.
   Why: No product brief exists yet. Start here to explore the idea.

2. /gaia-product-brief -- Create a product brief.
   Why: If you already know what you want to build, skip brainstorming
   and go straight to the brief.

3. /gaia-brownfield -- Onboard an existing codebase.
   Why: If you have existing code, this scans it and generates GAIA
   artifacts from the current state.

Run one of these now? Reply with the command name, or say "no" to exit.

With a description (mid-project)

> /gaia-help I need to review my code before merging

Your project is in Phase 4 (Implementation) -- sprint plan and stories
are present.

Suggested next command(s):

1. /gaia-review-code -- Pre-merge code review.
   Why: You asked about code review. This checks code quality, SOLID
   principles, and complexity.

2. /gaia-review-all -- Run all six reviews at once.
   Why: If the story is ready for full review, this runs code, QA,
   security, test, performance, and accessibility reviews together.

3. /gaia-review-security -- OWASP security review.
   Why: Security review is often paired with code review for sensitive
   changes.

Run one of these now? Reply with the command name, or say "no" to exit.

What to run next

Whatever /gaia-help suggests. The whole point of this command is to tell you what to run next. Common paths:

Troubleshooting

Suggestions seem off for my project's state

Phase detection relies on the presence of specific artifacts in .gaia/artifacts/planning-artifacts/, .gaia/artifacts/implementation-artifacts/, and .gaia/artifacts/test-artifacts/. If you moved or renamed artifacts, the detection may misjudge your phase. Run /gaia-help with an explicit description to bypass phase-based ranking.

Only /gaia is suggested

This happens when the command map file could not be loaded (rare). /gaia is the safe fallback -- it is the main orchestrator and can route you to any workflow.