name: sdd-validate description: Validate SDD JSON specs, auto-fix common issues, generate detailed reports, and analyze dependencies.

Spec Validation Skill

Overview

The Skill(foundry:sdd-validate) skill provides comprehensive validation for Spec-Driven Development (SDD) JSON specification files. It checks for structural consistency, auto-fixes common issues, generates detailed reports, and analyzes dependencies.

Key capabilities:

Validate JSON spec structure and hierarchy integrity
Auto-fix 13 common issue types with preview and backup support
Generate detailed validation reports in Markdown or JSON
Calculate comprehensive spec statistics (depth, coverage, complexity)
Analyze dependencies (cycles, orphans, deadlocks, bottlenecks)
Differentiated exit codes for warnings vs errors
Draft 07 JSON Schema validation (installs automatically when jsonschema is available; run pip install claude-skills[validation] to enable)

Understanding Exit Codes

Exit codes indicate the state of your spec, not command success/failure:

Exit 0: ✅ Spec is valid (no errors)
Exit 1: ⚠️ Spec has warnings (usable but improvable)
Exit 2: 🔧 Spec has errors (needs fixing) - THIS IS EXPECTED FOR NEW SPECS
Exit 3: ❌ File not found or access error (actual command failure)

Important: Exit code 2 means "I found errors in your spec" not "I failed to validate". The validate command succeeded at detecting issues - your spec just needs work. This is the normal starting point for most specs.

When to Use This Skill

Use Skill(foundry:sdd-validate) to:

Confirm a freshly created spec parses correctly
Auto-fix common validation issues
Check for structural errors before running other SDD skills
Generate validation reports for review or CI/CD
Analyze spec statistics and dependency issues

MCP Tooling

This skill interacts solely with the Foundry MCP server (foundry-mcp). Tools use the router+action pattern: mcp__plugin_foundry_foundry-mcp__<router> with action="<action>" (for example, mcp__plugin_foundry_foundry-mcp__spec action="validate", mcp__plugin_foundry_foundry-mcp__spec action="fix").
There is no CLI fallback. All instructions correspond to MCP invocations with named parameters.
Stay inside the repo root and rely on these helpers instead of reading spec JSON directly.

Core Workflow

Validate: mcp__plugin_foundry_foundry-mcp__spec action="validate" spec_id={spec-id} - Check for issues
Fix: mcp__plugin_foundry_foundry-mcp__spec action="fix" spec_id={spec-id} - Auto-fix common problems (creates backup)
Re-validate: Check for newly revealed issues
Repeat: Continue until error count stops decreasing
Manual fixes: Use --verbose for details when plateau is reached

Key concept: Error count decreasing = keep fixing. Plateau (same count for 2+ passes) = switch to manual fixes.

Key Concepts

Always Re-validate After Fixing

Fixing issues often reveals new problems that were previously hidden. Always run mcp__plugin_foundry_foundry-mcp__spec action="validate" after mcp__plugin_foundry_foundry-mcp__spec action="fix" to see the current state.

Error Count Progression

Track how error count changes across passes:

Decreasing (88 → 23 → 4) - Continue auto-fixing
Plateau (4 → 4 → 4) - Switch to manual fixes with --verbose

When to Stop Auto-Fixing

Switch to manual intervention when:

Error count unchanged for 2+ passes
mcp__plugin_foundry_foundry-mcp__spec action="fix" reports "skipped issues requiring manual intervention"
All remaining issues need context or human judgment

Input Format: Spec Names vs Paths

All validation commands accept both spec names and paths for maximum flexibility:

Spec name (recommended):

mcp__plugin_foundry_foundry-mcp__spec action="validate" spec_id="pomodoro-timer-2025-11-18-001"

Automatically searches in specs/pending/, specs/active/, specs/completed/, and specs/archived/.

Relative path:

mcp__plugin_foundry_foundry-mcp__spec action="validate" path="specs/pending/pomodoro-timer-2025-11-18-001.json"
mcp__plugin_foundry_foundry-mcp__spec action="validate" path="../other-project/specs/active/my-spec.json"

Absolute path:

mcp__plugin_foundry_foundry-mcp__spec action="validate" path="/full/path/to/my-spec.json"

Smart fallback: If you provide a path that doesn't exist, the command extracts the spec name and searches for it automatically.

Command Reference

validate (check)

Validate the JSON spec structure and print a summary.

mcp__plugin_foundry_foundry-mcp__spec action="validate" spec_id="{spec-id}"

Exit codes:

0 - Clean validation
1 - Warnings only
2 - Errors detected (expected when spec has issues)

Example output:

❌ Validation found 12 errors
   8 auto-fixable, 4 require manual intervention

   Errors:
   - 5 incorrect task count rollups
   - 2 missing metadata blocks
   - 1 orphaned node (task-5-3)
   - 2 circular dependencies
   - 2 parent/child mismatches

   Run 'spec action="fix"' to auto-fix 8 issues

fix

Auto-fix common validation issues with preview and backup support.

mcp__plugin_foundry_foundry-mcp__spec action="fix" spec_id="{spec-id}" dry_run=true

Parameters:

dry_run=true - Show what would be fixed without modifying files
create_backup=false - Skip backup creation (use with caution)

Auto-fixable issues:

Incorrect task count rollups
Missing metadata blocks
Orphaned nodes
Parent/child hierarchy mismatches
Malformed timestamps
Invalid status/type values
Bidirectional dependency inconsistencies

Example:

# Preview fixes
mcp__plugin_foundry_foundry-mcp__spec action="fix" spec_id="my-spec" dry_run=true
📋 Would apply 8 fixes:
   - Fix 5 task count rollups
   - Add 2 metadata blocks
   - Reconnect 1 orphaned node

⚠️  Would skip 4 issues requiring manual intervention:
   - task-3-2: Circular dependency
   - task-5-2: Dependency references non-existent task

# Apply fixes
mcp__plugin_foundry_foundry-mcp__spec action="fix" spec_id="my-spec"
✅ Applied 8 fixes
Created backup: my-spec.json.backup

# Re-validate
mcp__plugin_foundry_foundry-mcp__spec action="validate" spec_id="my-spec"
❌ Validation found 4 errors (manual intervention required)

stats

Calculate and display comprehensive spec statistics.

mcp__plugin_foundry_foundry-mcp__spec action="stats" spec_id="{spec-id}"

Shows:

Node, task, phase, and verification counts
Status breakdown (pending, in_progress, completed, blocked)
Hierarchy maximum depth
Average tasks per phase
Verification coverage percentage
Overall progress percentage

analyze-deps

Analyze dependencies for cycles, orphans, deadlocks, and bottlenecks.

Note: This command analyzes spec-wide dependency issues. For checking individual task dependencies, use mcp__plugin_foundry_foundry-mcp__task action="prepare" from sdd-next which includes dependency details by default in context.dependencies.

mcp__plugin_foundry_foundry-mcp__spec action="analyze-deps" spec_id="{spec-id}" bottleneck_threshold=3

Analyzes:

Cycles - Circular dependency chains
Orphaned - Tasks referencing missing dependencies
Deadlocks - Tasks blocked by each other
Bottlenecks - Tasks blocking many others

Example:

⚠️  Dependency Analysis: 3 issues found

Cycles (2):
  1. task-3-2 → task-3-5 → task-3-2
  2. task-4-1 → task-4-3 → task-4-1

Orphaned dependencies (1):
  task-5-2 references non-existent "task-2-9"

Recommendation: Fix circular dependencies first to unblock work

Common Patterns

For detailed issue-to-fix mapping, see reference.md#issue-to-fix-mapping

Issue → Fix Mapping

Incorrect task counts → Auto-fixed by recalculating from hierarchy
Missing metadata → Auto-fixed by adding empty metadata blocks
Orphaned nodes → Auto-fixed by reconnecting to parent
Circular dependencies → Requires manual fix (remove one edge)
Invalid timestamps → Auto-fixed to ISO 8601 format
Parent/child mismatches → Auto-fixed by correcting hierarchy references

Typical Fix Cycles

Most specs (2-3 passes):

Pass 1: 47 errors → fix → 8 errors
Pass 2: 8 errors → fix → 2 errors
Pass 3: 2 errors → fix → 0 errors ✅

Complex specs with circular deps (4-5 passes):

Pass 1: 88 errors → fix → 23 errors
Pass 2: 23 errors → fix → 4 errors
Pass 3: 4 errors → fix → 4 errors (plateau)
→ Manual: Remove circular dependencies
Pass 4: Validate → 0 errors ✅

Troubleshooting

For advanced troubleshooting and edge cases, see reference.md#advanced-troubleshooting

Auto-fix Succeeded But Errors Remain

This is normal. mcp__plugin_foundry_foundry-mcp__spec action="fix" reports success when it applies fixes successfully, not when all issues are resolved. Fixing one problem often reveals another (e.g., fixing parent-child mismatches may reveal orphaned nodes).

Solution: Re-validate to see remaining issues, then run fix again or address manually.

Error Count Plateau

When error count stays the same for 2+ passes:

Run mcp__plugin_foundry_foundry-mcp__spec action="validate" spec_id="{spec-id}" to see detailed issue information
Identify issues marked "requires manual intervention"
Manually fix issues that need context or human judgment
Re-validate after manual fixes

Understanding Spec Requirements:

Run mcp__plugin_foundry_foundry-mcp__spec action="schema-export" to see the complete spec structure, required fields, and valid values
The schema shows all field types, enum values (like status, type, verification_type), and optional vs required fields
Use this when validation errors reference unknown fields or invalid values

Common manual-only issues:

Circular dependencies (remove one dependency edge)
Orphaned dependencies (fix task ID typos)
Logical inconsistencies (requires understanding spec intent)
Custom metadata problems

How Many Passes Are Normal?

2-3 passes: Typical for most specs
5+ passes: May indicate circular dependencies or structural issues

Rule: If error count decreases each pass, keep going. If it plateaus, switch to manual.

Advanced Usage

Global Flags

Available on all commands:

--quiet / -q - Suppress progress messages
--verbose / -v - Show detailed information

Detailed Reference

For comprehensive documentation including:

Detailed issue-to-fix mapping tables
Manual fix patterns for circular dependencies
Advanced troubleshooting scenarios
Edge cases and CI/CD integration

See reference.md

sdd-validate