/gaia-test-gap-analysis

user-facing
Category:
Testing
Lifecycle phase:
Anytime
Arguments:
[--mode coverage|verification]

What it does

/gaia-test-gap-analysis scans your test plan and story files to find acceptance criteria that lack test coverage. It operates in two modes: coverage mode (default) cross-references acceptance criteria against the test plan, while verification mode cross-references generated test cases against actual execution results (JUnit XML, LCOV, or evidence JSON).

When to use it

  • You want to identify which acceptance criteria across your stories have no corresponding test case.
  • You want to verify that generated tests have actually been executed (verification mode).
  • You are preparing for a sprint review and need coverage metrics per epic.

Prerequisites

  • Story files should exist under .gaia/artifacts/implementation-artifacts/ with acceptance criteria sections.
  • A test plan is recommended at .gaia/artifacts/test-artifacts/test-plan.md for coverage mapping. Without it, only partial analysis is possible.

How to invoke

/gaia-test-gap-analysis
/gaia-test-gap-analysis --mode coverage
/gaia-test-gap-analysis --mode verification

What it does step by step

Coverage mode (default)

  1. Scan test plan Reads test-plan.md and builds a map of test case IDs to story keys.
  2. Scan story files Scans all story files and extracts acceptance criteria (AC items) from each.
  3. Cross-reference For each AC, checks whether a corresponding test case exists. Flags uncovered ACs and calculates per-story and aggregate coverage percentages.
  4. Per-module coverage Groups stories by epic and computes per-epic coverage metrics.
  5. Generate report Produces an executive summary, per-module coverage table, per-story detail, AC linkage table, and gap table.

Verification mode

  1. Scan generated tests Finds all generated test case files and ATDD files under .gaia/artifacts/test-artifacts/.
  2. Parse execution results Reads JUnit XML, LCOV, or evidence JSON files to build an executed-tests map.
  3. Cross-reference Classifies each generated test as EXECUTED or UNEXECUTED and calculates execution ratios.
  4. Generate report Produces a verification report with per-story execution ratios and an unverified tests table.

Inputs

InputSourceDescriptionExample
--modeArgument (optional, default: coverage)Analysis mode: coverage (AC-to-test mapping) or verification (executed-vs-planned)./gaia-test-gap-analysis --mode coverage
Test plan.gaia/artifacts/test-artifacts/test-plan.mdTest case definitions with story key mappings.--
Story files.gaia/artifacts/implementation-artifacts/Story files with acceptance criteria sections.--
Execution resultsProject test outputJUnit XML, LCOV, or evidence JSON files (verification mode only).--

Outputs

OutputLocationDescription
Gap analysis reportConversation outputCoverage or verification report printed to the terminal (read-only command -- no files modified).

Example session

> /gaia-test-gap-analysis

Executive Summary:
  Stories analyzed: 14
  ACs scanned: 42
  Gaps found: 6
  Overall coverage: 85.7%

Per-Module Coverage:
  E1   Authentication     12/14 ACs   85.7%   2 gaps
  E2   Dashboard          18/18 ACs  100.0%   0 gaps
  E3   Notifications      6/10 ACs    60.0%   4 gaps

Gap Table:
  E1-S3  AC2  uncovered-ac  high  "Password reset email not tested"
  E3-S1  AC1  uncovered-ac  high  "Push notification delivery not tested"
  ...

Run /gaia-fill-test-gaps to remediate these gaps now.

What to run next

Troubleshooting

"test-plan.md not found"

The command continues with partial analysis but cannot map ACs to test cases. Run /gaia-test-strategy --plan to create a test plan.

No story files found

Ensure story files exist under .gaia/artifacts/implementation-artifacts/. Run /gaia-create-story to create them.