/gaia-val-validate-plan

What it does

/gaia-val-validate-plan validates an implementation plan before you execute it. It verifies that file targets exist (or are correctly marked as new files), version bumps are sequential and valid, referenced architecture decisions are present, and the plan scope is complete -- catching issues that would waste time if discovered mid-implementation.

When to use it

• You are reviewing an implementation plan generated by /gaia-dev-story and want to verify its file targets are accurate before approving.
• A plan references version bumps and you want to confirm they are sequential relative to the current codebase version.
• You wrote a manual implementation plan and want to verify its references before starting work.

Prerequisites

• A plan artifact must exist. The plan can be any markdown document that describes implementation steps with file targets.

How to invoke

/gaia-val-validate-plan .gaia/artifacts/implementation-artifacts/plan-E3-S7.md

What it does step by step

1. Load and parse plan Reads the plan artifact and extracts all file targets (with action verbs like Create, Modify, Delete), version bump statements, and architecture decision references.
2. Verify file targets For each file target, checks whether the action makes sense: files to be created should not already exist; files to be modified must exist; files to be deleted must exist.
3. Verify version bumps For each version bump, reads the current version from the codebase and confirms the planned version is a valid sequential increment.
4. Verify completeness Checks whether the plan covers related files that typically need updating together (for example, modifying a workflow usually requires updating the manifest).
5. Cross-reference architecture If the plan references architecture decisions, verifies they exist in the architecture document and the plan aligns with their specifications.
6. Present findings Shows findings sorted by severity. You can approve, dismiss, or discuss each finding before they are written to the plan.
7. Write findings Appends approved findings under a "Plan Validation Findings" section in the plan artifact.

Inputs

Outputs

Example session

> /gaia-val-validate-plan .gaia/artifacts/implementation-artifacts/plan-E3-S7.md

Loading plan...
  8 file targets extracted.
  2 version bump statements found.
  1 ADR reference found.

Verifying file targets...
  Create src/services/auth.ts -- OK (does not exist yet)
  Modify src/routes/index.ts -- OK (exists)
  Modify src/models/nonexistent.ts -- CRITICAL: file does not exist

Verifying version bumps...
  package.json: 1.2.0 -> 1.3.0 -- OK (sequential minor bump)

Plan validation complete -- 1 CRITICAL finding.

| # | Severity | Finding                                          | Plan Step |
|---|----------|--------------------------------------------------|-----------|
| 1 | CRITICAL | File does not exist but plan says Modify          | Step 3    |

Approve findings? [y/n]

What to run next

• Fix the plan to address findings, then re-validate.
• If the plan is clean, approve it in /gaia-dev-story and proceed to implementation.

Troubleshooting

"Plan contains no steps to validate"

The plan document has no recognizable implementation steps or file targets. Ensure your plan uses action verbs (Create, Modify, Delete) with file paths.

"Planned version is not higher than current"

The version number in the plan is equal to or lower than the current version in the codebase. Update the plan with the correct next version.

Related commands