/gaia-validate-story
user-facingWhat it does
/gaia-validate-story performs a full validation of a story file against the codebase and ground truth. It checks that frontmatter fields are complete, acceptance criteria follow the expected format, file references are valid, and dependencies are accurate. The validator runs in an isolated context and records a PASSED, FAILED, or UNVERIFIED verdict.
When to use it
- You created or edited a story file and want to verify it is complete and accurate before implementation.
- A story failed review and you want to confirm the fix addressed the validation findings.
- You want to check whether a story is ready for the
ready-for-devstatus transition.
Prerequisites
- A story file must exist at
.gaia/artifacts/implementation-artifacts/epic-{epic_key}-{slug}/stories/{story_key}-{slug}.md.
How to invoke
/gaia-validate-story E3-S7The argument is the story key in E{n}-S{n} format.
What it does step by step
- Resolve story file Locates the story file using the story key. Fails if the file is not found or if multiple files match.
- Run validation Invokes the validator in an isolated context. The validator checks frontmatter completeness (15 required fields), acceptance criteria format, file path references, dependency accuracy, and structural conformance.
- Fix loop (up to 3 attempts) If the validator reports CRITICAL or WARNING findings, the command automatically attempts to fix them (adding missing frontmatter fields, correcting AC format, updating references). After each fix, it re-validates. The loop runs up to 3 attempts.
- Record verdict Records the terminal verdict (PASSED, FAILED, or UNVERIFIED) in the story's validation ledger. This verdict is separate from the six Review Gate rows used by review commands.
- Report results Displays the verdict and lists any remaining findings.
Inputs
| Input | Source | Description |
|---|---|---|
story-key | Command argument | The story to validate, in E{n}-S{n} format. |
| Story file | .gaia/artifacts/implementation-artifacts/epic-{epic_key}-{slug}/stories/{story_key}-{slug}.md | The story file containing frontmatter, acceptance criteria, and subtasks. |
Outputs
| Output | Location | Description |
|---|---|---|
| Validation verdict | Story validation ledger | PASSED, FAILED, or UNVERIFIED recorded for downstream consumers. |
| Updated story file | Story file path | Auto-fixes applied during the fix loop (if any). |
Example session
> /gaia-validate-story E5-S12
Resolving story file...
Found: .gaia/artifacts/implementation-artifacts/epic-E5-api-layer/stories/E5-S12-pagination.md
Running validation (attempt 1 of 3)...
2 findings: 1 WARNING (missing depends_on field), 1 INFO.
Applying fix: adding depends_on: [] to frontmatter...
Re-validating (attempt 2 of 3)...
0 CRITICAL/WARNING findings.
Story E5-S12 validation PASSED.What to run next
/gaia-dev-story-- implement the story now that it passes validation./gaia-fix-story-- if the story FAILED and needs manual intervention.
Troubleshooting
"Story file not found"
The story key did not match any file under .gaia/artifacts/implementation-artifacts/. Run /gaia-create-story first.
Verdict is UNVERIFIED
The validator could not complete its run (timeout or unavailable). Try again. If the issue persists, check your project configuration.
Verdict is FAILED after 3 attempts
Some findings could not be auto-fixed. Use /gaia-fix-story to address them manually.