/gaia-problem-solving

user-facing
Category:
Creative & Collaboration
Lifecycle phase:
Any
Arguments:
[topic or challenge]

What it does

/gaia-problem-solving applies systematic problem-solving with automatic artifact gathering and tiered resolution routing. It identifies root cause before proposing solutions, challenges assumed constraints, and routes the resolution to the right downstream flow (create story, add feature, or escalation).

When to use it

  • You have a specific problem (production issue, design flaw, process bottleneck) and want to identify root cause before jumping to solutions.
  • You want systematic constraint analysis -- identifying which constraints are real and which are assumed.
  • You need the resolution routed to the right downstream flow (create story, add feature, or escalation to architecture review).

Prerequisites

  • No strict prerequisites. Works best when planning artifacts exist for context.

Orchestration mode

When /gaia-problem-solving 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-problem-solving 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-problem-solving Login failures spiking after deploy

What it does step by step

  1. Gather context Automatically reads PRD, architecture, sprint status, test plan, and relevant code to understand the problem context. Asks you only for information that artifacts do not cover.
  2. Present plan Shows a structured analysis plan and waits for your approval before proceeding.
  3. Root cause analysis Separates symptoms from causes using systematic methodologies.
  4. Resolution routing Classifies the resolution as quick fix, bug, enhancement, or systemic and routes to the appropriate workflow.
  5. Generate artifact Writes the problem-solving report to .gaia/artifacts/creative-artifacts/problem-solving-{date}.md.

Inputs

InputSourceDescription
topicCommand argument (optional)The topic or challenge. If omitted, the command asks.

Outputs

OutputLocationDescription
Creative artifact.gaia/artifacts/creative-artifacts/The session output document.

Example session

> /gaia-problem-solving Login failures spiking after deploy

Gathering context from project artifacts...

Plan:
  1. Analyze error logs pattern
  2. Check auth middleware changes
  3. Verify token expiry configuration

Approve plan? [y/n] > y

Root cause: Token expiry set to 0 in new config.
Classification: Bug (quick fix)
Route: /gaia-create-story for hotfix.

Written to .gaia/artifacts/creative-artifacts/problem-solving-2026-05-07.md

What to run next

Troubleshooting

Topic not provided

The command asks for your topic interactively if no argument is given.

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.