planning-validate

name	planning-validate
description	Validates planning artifacts (spec.md, plan.md, data-model.md, contracts/) for quality, completeness, and consistency. Checks for mandatory sections, cross-artifact consistency, and constitution compliance. Always run after /speckit.plan completes.
version	0.0.1
license	MIT
compatibility	Requires spec kit with check-prerequisites.sh
metadata	{"author":"drillan","category":"quality-gate","repository":"https://github.com/drillan/speckit-gates"}

planning-validate

Validates planning artifacts for quality and consistency after /speckit.plan completes.

Purpose

This skill automatically validates your planning artifacts to catch specification gaps before task generation. It checks:

• spec.md completeness: All mandatory sections present with content
• plan.md executability: Technical context, project structure, and constitution check completed
• data-model.md consistency: Entities align with spec requirements (if exists)
• Contract coverage: API contracts defined for required endpoints (if contracts/ exists)
• Constitution compliance: Plan follows project constitution rules (if constitution.md exists)

Output

The skill outputs a Quality Assessment with:

• GREEN: All checks pass - proceed to /speckit.tasks
• YELLOW: Minor warnings - review but can proceed
• RED: Blockers found - must resolve before proceeding

Usage

This skill runs automatically after /speckit.plan. You can also run it manually:

npx skills run planning-validate

Exit Codes

Code	Status	Meaning
0	GREEN	All checks pass
1	YELLOW	Warnings present
2	RED	Blockers present
3	Error	Required files missing

Checks Performed

spec.md Checks

1. File exists and is readable
2. Summary section present with content
3. User Stories section present with at least one story
4. Functional Requirements section present with FR-XXX items
5. Success Criteria section present

plan.md Checks

1. File exists and is readable
2. Technical Context section present
3. Project Structure section present
4. Constitution Check section present (unless skipped)
5. Gate Result shows PASS status

data-model.md Checks (if exists)

1. Entities section present
2. At least one entity defined
3. Entity names are consistent with spec.md terminology

contracts/ Checks (if exists)

1. At least one contract file present
2. Contract files are valid markdown
3. Contract endpoints match spec.md requirements

constitution.md Checks (if exists)

1. Plan.md references constitution principles
2. No constitution violations in Gate Result

Documentation Impact Checks (Constitution Art.2)

1. plan.md contains Documentation Impact section
2. Documentation Impact section has a populated table with specs/, docs/, README.md entries

Blocker Examples

• "spec.md: Missing User Stories section"
• "plan.md: Constitution Check section shows FAIL status"
• "data-model.md: Entity 'UserAccount' not referenced in spec.md"

Recommendations

After receiving a RED or YELLOW status:

1. Review the specific blockers or warnings listed
2. Update the affected artifacts to address issues
3. Re-run /speckit.plan to regenerate plan.md
4. Run planning-validate again to verify fixes