design-validate

name	design-validate
description	Validate design doc structure and frontmatter. Use when checking design docs for compliance, ensuring proper formatting, or verifying metadata before commits.
allowed-tools	Read, Glob, Bash(bash *)
context	fork
agent	design-doc-agent

Design Documentation Validation

Validates design documentation files for structure, frontmatter, and quality compliance.

Overview

This skill validates design documentation by:

1. Reading the design configuration
2. Finding design docs for the specified module, recursing through nested subdirectories (<module>/packages/*.md and deeper) and skipping _archive/
3. Validating YAML frontmatter structure and values
4. Checking for required sections
5. Validating cross-references and links
6. Reporting issues with severity levels
7. Providing actionable fix recommendations

Quick Start

Basic validation:

/design-docs:design-validate effect-type-registry

Validate specific file:

/design-docs:design-validate effect-type-registry cache-optimization.md

Strict mode (additional quality checks):

/design-docs:design-validate all --strict

How It Works

1. Parse Parameters

• module: Module name to validate (or "all" for all modules) [REQUIRED]
• file: Specific file to validate (default: all files in module)
• strict: Enable strict mode with additional checks (default: false)

2. Load Configuration

Read .claude/design/design.config.json to get:

• Module configuration and paths
• Quality standards
• Required frontmatter fields
• Minimum section requirements

3. Find and Validate Documents

Use Glob to find design docs, then for each file:

Frontmatter Validation:

• Validate YAML syntax
• Check all required fields exist
• Verify field values are correct type and format
• Validate dates are in order (created ≤ updated ≤ last-synced)
• Check status matches completeness level

Structure Validation:

• Verify required sections exist
• Check TOC matches headings (if required)
• Validate document title

Cross-Reference Validation:

• Check paths in related array exist
• Check paths in dependencies array exist (when the field is present — it is optional)
• Check paths in implementation-plans array exist (if present)
• Validate bidirectional plan-design links
• Validate internal markdown links

Quality Checks (strict mode only):

• Completeness accuracy
• Status appropriateness
• Documentation quality (section length, content depth)

4. Report Results

Generate a validation report with issues categorized by severity:

• ERROR: Must be fixed (blocks)
• WARNING: Should be fixed
• INFO: Nice to have

Supporting Documentation

When you need detailed information about validation rules or error messages, load the appropriate supporting file:

For Frontmatter Rules

See frontmatter-rules.md for:

• Complete field requirements table
• Status-completeness matrix
• Date validation rules
• Category validation
• Required sections by category

Load when: Working with frontmatter validation or debugging field errors

For Error Messages

See error-messages.md for:

• All error message formats
• Fix instructions for each error type
• Common validation failures

Load when: User has validation errors and needs to fix them

For Usage Examples

See examples.md for:

• Complete usage scenarios
• Example outputs for different validation states
• Multi-module validation examples

Load when: User wants to see concrete examples of validation output

Validation Flow

1. Parse user parameters
   ↓
2. Load design.config.json
   ↓
3. Find module(s) and design docs
   ↓
4. For each doc:
   - Validate frontmatter
   - Check structure
   - Verify cross-references
   - Run quality checks (if strict)
   ↓
5. Generate report with:
   - Summary stats
   - Issues by file
   - Recommendations

Exit Codes

• ✅ PASS: No errors found
• ⚠️ WARNINGS: Warnings but no errors
• ❌ FAIL: Errors found, must fix

Plan Link Validation

Design docs can reference implementation plans via the implementation-plans field in frontmatter. This skill validates:

Plan Reference Validation

• Plans listed in implementation-plans array exist in .claude/plans/
• Plan paths are relative (e.g., ../plans/my-plan.md)
• Plans are not archived (warning if in _archive/)

Bidirectional Link Validation

• If a design doc references a plan, verify plan exists
• If a plan references a design doc (via design-docs field), verify design doc references the plan back
• Warn if links are unidirectional (missing backlink)

Example validation output:

✓ Design doc: effect-type-registry/observability.md
  ✓ Plan reference: ../plans/observability-phase-2.md (exists)
  ✓ Bidirectional link: Plan references this design doc

⚠ Design doc: effect-type-registry/cache-optimization.md
  ✓ Plan reference: ../plans/cache-optimization-plan.md (exists)
  ⚠ Unidirectional link: Plan does not reference this design doc
  Fix: Add 'effect-type-registry/cache-optimization.md' to plan's
       design-docs array

Integration

This skill integrates with:

• /design-docs:design-init - Validate newly created docs
• /design-docs:design-update - Validate after updates
• /design-docs:design-sync - Validate after syncing with code
• /design-docs:plan-create - Validate plan-design links when creating plans
• /design-docs:plan-validate - Complementary validation for plans
• CI/CD pipelines - Pre-commit or PR validation

Standalone Script

A standalone bash validation script ships with the plugin:

bash "${CLAUDE_PLUGIN_ROOT}/skills/design-validate/scripts/validate.sh" [module|all]

This script can be:

• Run directly from command line
• Integrated into CI/CD pipelines
• Used in pre-commit hooks
• Called from other automation tools

Exit codes:

• 0 - All validations pass (no errors, no warnings)
• 0 - Pass with warnings (no errors, but warnings present)
• 1 - Validation failed (errors found)

Success Criteria

A design doc passes validation if:

• ✅ Valid YAML frontmatter with all required fields
• ✅ Field values meet validation rules
• ✅ Required sections present
• ✅ Cross-references exist (related, dependencies, plans)
• ✅ Plan links are bidirectional (if implementation-plans present)
• ✅ Markdown linting passes
• ✅ Status matches completeness level