/gaia-val-validate

user-facing
Category:
Validation
Lifecycle phase:
4 -- Implementation
Arguments:
[artifact-path]

What it does

/gaia-val-validate validates any GAIA artifact (PRD, architecture, UX design, test plan, story, etc.) against the actual codebase and the validator's ground-truth knowledge. It scans file paths referenced in the artifact, verifies factual claims against the filesystem, cross-references against ground truth when available, and reports findings classified by severity: CRITICAL, WARNING, or INFO.

When to use it

  • You just updated a planning artifact (PRD, architecture, epics) and want to verify that all file references and factual claims are accurate.
  • A review or triage flagged potential inaccuracies in an artifact and you want a systematic verification.
  • You want to check an artifact before sharing it with stakeholders to ensure all technical references are current.

Prerequisites

  • An artifact file must exist. Provide the path to the file you want to validate as the command argument.
  • Ground truth improves accuracy. If you have run /gaia-refresh-ground-truth recently, the validator cross-references claims against the ground-truth snapshot. Without it, validation still runs using filesystem checks only.

How to invoke

/gaia-val-validate .gaia/artifacts/planning-artifacts/architecture.md

The argument is the path to the artifact you want to validate.

What it does step by step

  1. Load and parse artifact Reads the target artifact and maps its heading structure. For large files, it splits the document into chunks for more granular validation.
  2. Detect artifact type Determines whether this is a PRD, architecture doc, UX design, test plan, or another artifact type. Each type has its own structural validation rules (required sections, expected format). Unknown types skip structural validation but still run factual checks.
  3. Extract verifiable claims Scans the artifact for file paths, component counts, version numbers, agent/workflow references, and other factual assertions that can be checked against the filesystem.
  4. Verify against the codebase For each file-path claim, checks whether the file actually exists on disk. For content claims, reads the referenced file and compares against what the artifact states. Caps scanning at 40 files per run to keep validation fast.
  5. Cross-reference ground truth If ground-truth data is available, cross-references claims against it to catch discrepancies the filesystem check alone might miss.
  6. Classify and present findings Compiles all findings into a severity-sorted table (CRITICAL first, then WARNING, then INFO). You can approve, dismiss, or discuss each finding.
  7. Write approved findings Appends the approved findings to the artifact under a "Validation Findings" section so the next editor can see what was flagged.
  8. Save to validator memory Records the validation session in the validator's memory sidecar for future reference.

Auto-fix loop

When invoked by other commands (like /gaia-create-prd or /gaia-create-arch), this validator runs inside a 3-iteration auto-fix loop. The upstream command writes the artifact, validates it, fixes any CRITICAL or WARNING findings, and re-validates -- up to 3 times. If findings persist after 3 iterations, you are prompted to continue, accept as-is, or abort.

Inputs

Input Source Description
artifact-path Command argument Path to the artifact file to validate.
Ground truth _memory/validator-sidecar/ground-truth.md Optional. Provides cached project metadata for cross-referencing.

Outputs

Output Location Description
Validation findings Appended to the artifact A "Validation Findings" section with severity, finding, and reference columns.
Validator decision log _memory/validator-sidecar/decision-log.md Session record appended to the validator's memory.

Example session

> /gaia-val-validate .gaia/artifacts/planning-artifacts/architecture.md

Loading artifact...
  Path: .gaia/artifacts/planning-artifacts/architecture.md
  Type: Architecture document
  12 sections identified, 4 chunks for validation.

Extracting verifiable claims...
  Found 23 file-path claims, 5 component-count claims.

Verifying against codebase...
  Scanning 28 files... done.

Cross-referencing ground truth...

Findings:

| # | Severity | Section           | Finding                                         |
|---|----------|-------------------|-------------------------------------------------|
| 1 | CRITICAL | System Components | Referenced file not found: src/services/auth.ts |
| 2 | WARNING  | Data Architecture | Stated 8 models but filesystem shows 7          |
| 3 | INFO     | Security          | Ground truth entry slightly outdated             |

Summary: 3 findings -- 1 CRITICAL, 1 WARNING, 1 INFO

Review each finding: [approve] [dismiss] [discuss]
> approve all

Writing approved findings to architecture.md...
Saving to validator memory...
Done.

What to run next

  • /gaia-refresh-ground-truth -- if ground truth was missing or outdated during validation.
  • /gaia-val-save -- to persist specific validation decisions to the validator's memory.
  • Fix the issues in the artifact, then re-run /gaia-val-validate to confirm fixes.

Troubleshooting

"Artifact not found"

The file path you provided does not exist. Double-check the path and ensure the artifact has been created.

"Ground truth not available"

This is an INFO-level note, not an error. Validation proceeds with filesystem verification only. Run /gaia-refresh-ground-truth to improve validation accuracy.

Too many findings

If the artifact has not been updated in a while, it may have drifted from the codebase. Fix the highest-severity findings first, then re-validate.