/gaia-epic-status

user-facing
Category:
Sprint Management
Lifecycle phase:
4 -- Implementation
Arguments:
[epic-key?]

What it does

/gaia-epic-status displays a completion dashboard across all epics -- showing how many stories in each epic are done, in progress, in review, or still in the backlog. Optionally filters to a single epic when you pass an epic key.

When to use it

  • You want a bird's-eye view of project progress across all epics.
  • You need to identify which epics are close to completion and which are lagging.
  • A stakeholder asks for a progress report.

Prerequisites

  • Epics and stories must exist. .gaia/artifacts/planning-artifacts/epics-and-stories.md is required.

How to invoke

/gaia-epic-status

Shows all epics.

/gaia-epic-status E3

Filters to Epic 3 only.

What it does step by step

  1. Parse epics Reads the epics-and-stories document and extracts every epic with its story list.
  2. Resolve story statuses Reads story statuses from the sprint tracking file. If it is missing, falls back to scanning individual story files directly.
  3. Compute metrics For each epic: total stories, done count, completion percentage, and per-status counts (backlog, ready, in-progress, review, done, blocked).
  4. Render dashboard Displays a table sorted by epic number with an overall summary line.
  5. Suggest next actions Recommends the most relevant command based on the data.

Inputs

InputSourceDescription
Epics and stories.gaia/artifacts/planning-artifacts/epics-and-stories.mdEpic overview and story lists.
Sprint tracking.gaia/state/sprint-status.yamlPer-story status (primary source).
Story files.gaia/artifacts/implementation-artifacts/Fallback source when sprint tracking is unavailable.

Outputs

Text output only. This command does not create or modify any files.

Example session

> /gaia-epic-status

| Epic | Name                | Done | Total | %   | Backlog | Ready | In-Prog | Review | Done | Blocked |
|------|---------------------|------|-------|-----|---------|-------|---------|--------|------|---------|
| E1   | User Management     | 4    | 5     | 80  | 0       | 0     | 0       | 1      | 4    | 0       |
| E2   | Notifications       | 1    | 4     | 25  | 2       | 1     | 0       | 0      | 1    | 0       |
| E3   | Dashboard           | 2    | 6     | 33  | 1       | 2     | 1       | 0      | 2    | 0       |

Overall: 7 / 15 stories done (46%)

What to run next

Troubleshooting

"sprint-status.yaml not found -- deriving status from story files"

This is normal before the first sprint is planned. The dashboard still works by reading each story file directly.

Epic key not found

If you pass an epic key that does not exist in epics-and-stories.md, the command lists available epic keys so you can correct the input.