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
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-validate effect-type-registry

Validate specific file:

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

Strict mode (additional quality checks):

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

Standalone Script

A standalone bash validation script is available at:

.claude/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