/gaia-test-strategy

user-facing

Category:: Testing
Lifecycle phase:: Setup
Arguments:: [--plan | --scaffold [--service <path>] [--add <type>] [--cross-service]]

What it does

/gaia-test-strategy is the unified entry point for test strategy and test framework setup. It operates in two modes: --plan designs a test strategy document with risk assessment, test levels, and quality gates; --scaffold generates framework configuration, directory structure, and runner scripts for your detected stack.

Two artifacts, two names (do not confuse them):

test-strategy.md — the strategy document this command produces under --plan. Covers risk assessment, test levels (unit/integration/e2e), pyramid ratios, coverage targets, and quality gates. Authored once early in Phase 3; updated incrementally.
test-plan.md — the per-FR test-case catalogue that /gaia-trace produces (one row per FR/NFR, mapped to story + test cases). This skill also writes a sibling test-plan.md alias next to test-strategy.md as a downstream-gate mitigation. Authored when requirements + stories are stable.

The mental-model trap is that "test plan" naturally evokes the strategy doc — but if you want the high-level strategy, you want test-strategy; if you want the per-FR test-case catalogue, you want test-plan, produced by /gaia-trace. Both now live under .gaia/artifacts/planning-artifacts/ (the canonical "docs-about-testing" home).

When to use it

Your project needs a test strategy document before implementation begins.
You want to scaffold test infrastructure (config files, directories, fixtures) for a new or existing project.
You are adding a new test type (performance, contract, accessibility) to an existing setup.

Prerequisites

Project configuration must exist. .gaia/config/project-config.yaml is required. Run /gaia-init or /gaia-brownfield first.

How to invoke

/gaia-test-strategy --plan
/gaia-test-strategy --scaffold
/gaia-test-strategy --scaffold --service backend
/gaia-test-strategy --scaffold --service all
/gaia-test-strategy --scaffold --add perf
/gaia-test-strategy --scaffold --cross-service
/gaia-test-strategy

With no arguments, an interactive menu appears to choose the mode.

What it does step by step

Plan mode

Load project context Reads architecture, PRD, and existing test strategy for incremental updates.
Risk assessment Identifies high-risk areas and rates them using probability-impact scoring.
Test strategy Defines test levels per component, coverage targets, and quality gates.
Write output Saves the strategy to .gaia/artifacts/planning-artifacts/test-strategy.md (the canonical home for docs-about-testing). For projects pre-dating the migration, writes to .gaia/artifacts/test-artifacts/strategy/test-strategy.md (legacy read-compat) and surfaces a migrate-planning-vs-test.sh advisory.

Scaffold mode

Detect stacks Reads project-config.yaml stacks. Single-stack projects skip the service picker.
Select framework Recommends the appropriate test framework for the detected stack (Vitest, pytest, JUnit 5, etc.).
Generate scaffolding Creates config files, directory structure, and test runner scripts.
Update config Updates the test_execution section and offers CI regeneration.

Inputs

Input	Source	Description	Example
`--plan`	Argument (optional)	Author or update a test strategy document.	`/gaia-test-strategy --plan`
`--scaffold`	Argument (optional)	Generate framework scaffolding (config, directories, fixtures).	`/gaia-test-strategy --scaffold`
`--service`	Argument (optional, scaffold only)	Restrict scaffolding to a single service, or use `all`/`root`.	`/gaia-test-strategy --scaffold --service backend`
`--add`	Argument (optional, scaffold only)	Add a new test type to an existing service scaffold.	`/gaia-test-strategy --scaffold --add perf`
`--cross-service`	Argument (optional, scaffold only)	Generate cross-service E2E tests at `tests/e2e/`.	`/gaia-test-strategy --scaffold --cross-service`
Project config	`.gaia/config/project-config.yaml`	Stack definitions and test execution settings.	--
Architecture	`.gaia/artifacts/planning-artifacts/architecture.md`	System components and risk areas (plan mode).	--

Outputs

Output	Location	Description
Test strategy	`.gaia/artifacts/planning-artifacts/test-strategy.md` (canonical)	Risk assessment, test levels, quality gates (plan mode). Legacy `.gaia/artifacts/test-artifacts/strategy/test-strategy.md` is read-compat for projects pre-dating the migration.
Test-plan alias	`.gaia/artifacts/planning-artifacts/test-plan.md` (sibling alias)	Written next to `test-strategy.md` as a downstream-gate mitigation — downstream gates that read `test-plan.md` (e.g. `/gaia-create-epics`) find it without a manual copy.
Config files	Project root	Test runner configuration (scaffold mode).
Directory structure	`tests/unit/`, `tests/integration/`, etc.	Test directory skeleton (scaffold mode).

Example session

> /gaia-test-strategy --scaffold

Detected stack: typescript (from package.json).
Recommended framework: Vitest for unit/integration, Playwright for E2E.

Scaffolding:
  Created vitest.config.ts
  Created tests/unit/
  Created tests/integration/
  Created tests/e2e/
  Added npm scripts: test, test:unit, test:int, test:e2e

Updated test_execution in project-config.yaml.
Regenerate CI config now? [y/n]

What to run next

/gaia-dev-story -- implement stories using the scaffolded test infrastructure.
/gaia-atdd -- generate acceptance test skeletons for high-risk stories.

Troubleshooting

"project-config.yaml not found"

Run /gaia-init or /gaia-brownfield first.

"--plan and --scaffold are mutually exclusive"

Choose one mode per invocation, or run with no arguments for the interactive menu.

Command	Relationship
`/gaia-atdd`	Generates acceptance test skeletons using the scaffolded framework.
`/gaia-test-gap-analysis`	Identifies coverage gaps against the test strategy.