// Validate SDD JSON specs, auto-fix common issues, generate detailed reports, and analyze dependencies.
| name | sdd-validate |
| description | Validate SDD JSON specs, auto-fix common issues, generate detailed reports, and analyze dependencies. |
The Skill(sdd-toolkit: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:
jsonschema is available; run pip install claude-skills[validation] to enable)Exit codes indicate the state of your spec, not command success/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.
Use Skill(sdd-toolkit:sdd-validate) to:
sdd validate {spec-id} - Check for issuessdd fix {spec-id} - Auto-fix common problems (creates backup)--verbose for details when plateau is reachedKey concept: Error count decreasing = keep fixing. Plateau (same count for 2+ passes) = switch to manual fixes.
Fixing issues often reveals new problems that were previously hidden. Always run sdd validate after sdd fix to see the current state.
Track how error count changes across passes:
--verboseSwitch to manual intervention when:
sdd fix reports "skipped issues requiring manual intervention"All sdd-validate commands accept both spec names and paths for maximum flexibility:
Spec name (recommended):
sdd validate pomodoro-timer-2025-11-18-001
Automatically searches in specs/pending/, specs/active/, specs/completed/, and specs/archived/.
Relative path:
sdd validate specs/pending/pomodoro-timer-2025-11-18-001.json
sdd validate ../other-project/specs/active/my-spec.json
Absolute path:
sdd validate /full/path/to/my-spec.json
Smart fallback: If you provide a path that doesn't exist (e.g., specs/pending/my-spec.json), the command extracts the spec name (my-spec) and searches for it automatically.
Validate the JSON spec structure and print a summary.
sdd validate {spec-id} [--verbose]
Flags:
--verbose - Show detailed issue information with locations--report - Generate validation report alongside spec--report-format {markdown,json} - Choose report formatExit codes:
0 - Clean validation1 - Warnings only2 - Errors detected (expected when spec has issues)Example:
$ sdd validate my-spec
❌ 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 'sdd fix my-spec' to auto-fix 8 issues
Use '--verbose' for detailed issue information
Auto-fix common validation issues with preview and backup support.
sdd fix {spec-id} [--preview] [--dry-run] [--no-backup]
Flags:
--preview / --dry-run - Show what would be fixed without modifying files--no-backup - Skip backup creation (use with caution)--diff - Show before/after changes--diff-format {markdown,json} - Choose diff formatAuto-fixable issues:
Selective fix application:
# Apply specific fixes by ID
sdd fix {spec-id} --select counts.recalculate
# Apply all fixes in a category
sdd fix {spec-id} --select metadata
# Apply multiple specific fixes
sdd fix {spec-id} --select counts.recalculate metadata.ensure:task-001
Example:
$ sdd fix my-spec --preview
📋 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
$ sdd fix my-spec
✅ Applied 8 fixes
Created backup: my-spec.json.backup
$ sdd validate my-spec
❌ Validation found 4 errors (manual intervention required)
Generate a detailed validation report with stats and dependency analysis.
sdd report {spec-id} [--output <path>]
Flags:
--output - Output file path (use - for stdout)--bottleneck-threshold N - Minimum tasks blocked to flag bottleneck (default: 3)Report includes: validation summary, categorized issues, statistics, and dependency findings.
Calculate and display comprehensive spec statistics.
sdd stats {spec-id}
Shows:
Analyze dependencies for cycles, orphans, deadlocks, and bottlenecks.
Note: This command analyzes spec-wide dependency issues. For checking individual task dependencies, use sdd prepare-task from sdd-next which includes dependency details by default in context.dependencies (e.g., sdd prepare-task {spec-id} {task-id}). The standalone sdd check-deps command is rarely needed now.
sdd analyze-deps {spec-id} [--bottleneck-threshold N]
Analyzes:
Example:
$ sdd analyze-deps my-spec
⚠️ 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
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 ✅
This is normal. sdd 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.
When error count stays the same for 2+ passes:
sdd validate {spec-id} --verbose to see detailed issue informationUnderstanding Spec Requirements:
sdd schema to see the complete spec structure, required fields, and valid valuesstatus, type, verification_type), and optional vs required fieldsCommon manual-only issues:
Rule: If error count decreases each pass, keep going. If it plateaus, switch to manual.
Available on all commands:
--quiet / -q - Suppress progress messages--verbose / -v - Show detailed informationTask preparation skill for spec-driven workflows. Reads specifications, identifies next actionable tasks, and creates detailed execution plans. Use when ready to implement a task from an existing spec - bridges the gap between planning and coding.
Targeted query capabilities for machine-readable codebase documentation with cross-reference tracking, call graph analysis, and workflow automation. Enables fast lookups of classes, functions, dependencies, and function relationships without parsing source code.
LLM-powered documentation generation for narrative architecture docs, tutorials, and developer guides. Uses AI consultation to create contextual, human-readable documentation from code analysis and spec data.
Plan-first development methodology that creates detailed specifications before coding. Use when building features, refactoring code, or implementing complex changes. Creates structured plans with phases, file-level details, and verification steps to prevent drift and ensure production-ready code.
AI-powered PR creation after spec completion. Analyzes spec metadata, git diffs, commit history, and journal entries to generate comprehensive PR descriptions with user approval before creation.
Comprehensive pytest testing and debugging framework. Use when running tests, debugging failures, fixing broken tests, or investigating test errors. Includes systematic investigation workflow with external AI tool consultation and verification strategies.