/gaia-market-research

user-facing

Category:: Discovery & Research
Lifecycle phase:: 1 -- Analysis
Arguments:: [market or industry focus]

What it does

/gaia-market-research conducts a structured market research session covering competitive analysis, customer segmentation, and market sizing (TAM/SAM/SOM). If web access is available via MCP tools, it augments findings with live research; otherwise it works with your input and general knowledge.

When to use it

You want to analyze competitors, define customer segments, and estimate market size before writing a product brief or PRD.
You want to validate the competitive landscape from a prior brainstorm with deeper analysis.

Prerequisites

None required. Web access (MCP tools) improves results but is not mandatory -- the command notes any limitations in the output.

Orchestration mode

When /gaia-market-research 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-market-research skill declares orchestration_class: heavy-procedural in its SKILL.md frontmatter. Heavy-procedural 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-market-research

/gaia-market-research developer productivity tools

What it does step by step

Scope definition Asks: what market/industry, specific competitors to analyze, and geographic scope (global/regional/local).
Web access check Tests whether MCP web tools are available. Notifies you if proceeding with general knowledge only.
Competitive analysis Identifies direct and indirect competitors. For each: strengths, weaknesses, market position, pricing model. Creates a competitive positioning matrix.
Customer research Defines target customer segments, analyzes behavior patterns, and identifies underserved needs and market gaps.
Market sizing Estimates TAM (Total Addressable Market), SAM (Serviceable Addressable Market), and SOM (Serviceable Obtainable Market) with all assumptions stated clearly.
Generate output Writes the market research report with six sections: executive summary, competitive analysis, customer segments, market sizing, key findings, and strategic recommendations.

Inputs

Input	Source	Description
`focus`	Command argument (optional)	Market or industry to research.

Outputs

Output	Location	Description
Market research report	`.gaia/artifacts/planning-artifacts/market-research.md`	Competitive analysis, customer segments, TAM/SAM/SOM, and strategic recommendations.

Output schema

The finalize.sh checklist enforces the following H2 section names verbatim against the produced artifact at .gaia/artifacts/planning-artifacts/market-research.md. Authors (human or sub-agent) must reproduce these headings exactly — the optional numbered/lettered outline prefix is accepted (e.g. ## 1. Executive Summary, ## 1b. Executive Summary, ## 1.2 Executive Summary), but the section name itself must match.

## Executive Summary
## Market Sizing
## Customer Segments
## Competitive Analysis
## Key Findings
## Strategic Recommendations

A missing required section causes the matching SV-NN check to FAIL with the heading name in the violation line. The heading_present() helper (shared at plugins/gaia/scripts/lib/heading-present.sh) accepts every variant listed above — so do not editorialize the section name to satisfy the gate, just use one of the documented heading forms.

Example session

> /gaia-market-research developer productivity tools

What market or industry do you want to research?
> Developer productivity and code quality tools

Are there specific competitors you want analyzed?
> SonarQube, CodeRabbit, Snyk

What geographic scope?
> Global

Web access: available (MCP tools detected).

Competitive Analysis:
  3 direct competitors analyzed + 4 indirect
  Positioning matrix generated

Market Sizing:
  TAM: $15.2B (global DevOps market, 2025)
  SAM: $3.8B (code quality + review segment)
  SOM: $190M (mid-market, first 3 years)
  Assumptions: 12% CAGR, 5% market penetration...

Report written to:
  .gaia/artifacts/planning-artifacts/market-research.md

What to run next

/gaia-product-brief -- consolidate findings into a product brief.
/gaia-domain-research -- explore domain-specific regulations and trends.
/gaia-tech-research -- evaluate technology options.

Troubleshooting

"Web access unavailable"

The command proceeds with general knowledge only and notes this limitation in the output. Results may be less comprehensive. Configure MCP web tools if live research is important.

Fewer than 3 competitors

Provide specific competitor names when prompted to ensure the minimum threshold is met.

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

Command	Relationship
`/gaia-brainstorm`	Often precedes market research -- provides initial competitive context.
`/gaia-product-brief`	Primary successor -- consolidates market findings into a brief.
`/gaia-domain-research`	Complementary research focused on domain regulations and trends.