/gaia-retro

What it does

/gaia-retro facilitates a structured post-sprint retrospective. It loads sprint data to seed the discussion with data-driven insights, walks through what went well, what could improve, and action items, then writes an immutable retrospective artifact. Action items are persisted to a structured tracker and velocity data is recorded for trend analysis.

When to use it

• A sprint has finished and you want to capture lessons learned.
• You want data-driven insights: which stories passed reviews on the first try, which cycled back, what the velocity was.

Prerequisites

• A sprint should be active or recently completed. The command reads sprint-status.yaml for sprint data. Without it, you must provide the sprint ID manually.

Not YOLO-able. This skill requires interactive AskUserQuestion confirmation gates (went-well, did-not-go-well, action-items elicitation) and has no non-interactive fallback. Operators running unattended must script the underlying boundary writes via the documented workaround pattern — passing yolo as an argument does NOT bypass these gates; the LLM HALTS at the first prompt waiting for input. Sister surface to /gaia-sprint-review, which also requires interactive boundaries.

Orchestration mode

When /gaia-retro starts in subagent mode (Mode A -- the default), the framework emits a one-shot warning to your conversation. The warning text:

────────────────────────────────────────────────────────────────────────────
GAIA orchestration: running in subagent mode (Mode A)

The skill you're invoking belongs to a class (heavy-procedural or
conversational) whose output benefits from cross-step context. Mode A
dispatches each sub-agent in its own forked context, so context may
be lossy between steps — sub-agents return summaries, not full reasoning.

For the full-fidelity experience, enable Mode B (Agent Teams):
  1. Set CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 in your environment.
  2. Add orchestration.mode: team to .gaia/config/project-config.yaml.

Mode B uses persistent teammates that preserve in-conversation state
across dispatches.

This warning is shown once per session.
────────────────────────────────────────────────────────────────────────────

Why Mode B is better for this command

The /gaia-retro skill declares orchestration_class: conversational in its SKILL.md frontmatter. Conversational skills produce output that benefits from cross-step context -- under Mode A every sub-agent dispatch runs in its own forked context and can only return a summary back to the orchestrator, losing the full reasoning trace of every prior step. Mode B uses persistent teammates that retain in-conversation state across dispatches, so each agent's contribution can build on what was said before instead of receiving only a summary.

How to enable Mode B

Both steps are required. If either is missing, the framework falls back silently to Mode A and the warning fires again on the next session.

Step 1 -- set the environment variable:

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

Add this to your shell rc file to persist across sessions, or set it in Claude Code's settings.json.

Step 2 -- add the YAML block to .gaia/config/project-config.yaml:

orchestration:
  mode: team

One-shot semantics

The warning is emitted once per Claude Code session. A marker file at _memory/checkpoints/orchestration-warning-shown.<session-id> suppresses the warning for the rest of the session. Starting a new session re-emits the warning once.

How to invoke

/gaia-retro

Uses the current sprint. Optionally pass a sprint ID:

/gaia-retro sprint-3

What it does step by step

1. Resolve sprint Identifies the sprint from the argument or reads the current sprint ID from .gaia/state/sprint-status.yaml.
2. Extract review data Scans review artifacts for verdicts and key findings.
3. Load sprint metrics Computes completion rate, velocity, first-pass review rate, blocked stories, and carryover.
4. What went well Presents data-driven positive findings and prompts you to add, confirm, or modify.
5. What could improve Presents data-driven improvement areas and prompts you to add, confirm, or modify.
6. Action items Proposes concrete action items with owners and target sprints. Persists them to .gaia/state/action-items.yaml.
7. Val sidecar write REQUIRED before finalize Persists the Val decision payload via val-sidecar-write.sh. Under GAIA_FINALIZE_SENTINEL_REQUIRED=1 (the default in CI and most production configs) this step is MANDATORY — finalize.sh HALTs if the sentinel is absent. A missing sentinel produces the canonical error "retro finalize gate sentinel missing". Do not skip this step.
8. Cross-retro pattern detection Scans prior retrospectives for recurring themes and auto-escalates aged items.
9. Write artifact Saves the retrospective to .gaia/artifacts/implementation-artifacts/retrospective/retrospective-{sprint_id}-{date}.md.

Inputs

Outputs

Example session

> /gaia-retro

Resolving sprint... sprint-4 (current).

Sprint-4 metrics:
  Stories: 6 total, 5 done, 1 carried over
  Velocity: 19/21 points delivered (90%)
  First-pass review rate: 3/5 (60%)
  Blocked stories: 1 (E4-S6, resolved via course correction)

--- What Went Well ---
  Data-driven:
  - E5-S12, E3-S10, E4-S7 passed all 6 reviews on first try.
  - Velocity met plan (90%).

  Add or modify? > Confirm

--- What Could Improve ---
  Data-driven:
  - E3-S9 failed security review twice before passing.
  - E4-S6 blocked for 4 days by third-party API outage.

  Add or modify? > Add: Test data setup was manual and slow.

--- Action Items ---
  AI-15: Add mock server for third-party APIs (owner: Theo, target: sprint-5)
  AI-16: Automate test data seeding (owner: dev team, target: sprint-5)

  Add, remove, or modify? > Confirm

Retrospective written to .gaia/artifacts/implementation-artifacts/retrospective-sprint-4-2026-05-07.md.
Action items persisted (2 new items).
Velocity data recorded.

What to run next

• /gaia-action-items -- resolve action items before the next sprint.
• /gaia-sprint-plan -- plan the next sprint.

Troubleshooting

"sprint-status.yaml not found"

Provide the sprint ID explicitly: /gaia-retro sprint-3.

Retrospective file already exists

A timestamp suffix is added automatically to avoid overwriting prior retrospectives.

I keep seeing the GAIA orchestration warning every time I start this command

The warning is shown once per session, so if it fires again that's a new session -- not a per-skill repeat. If you want to silence it entirely, enable Mode B (full-fidelity orchestration via Agent Teams). Both of these conditions must be true:

• echo $CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS returns 1 (not empty)
• .gaia/config/project-config.yaml contains:

  orchestration:
    mode: team

If either is missing the framework silently uses Mode A and re-emits the warning each session.

Related commands