spec-fragment-validate

name	spec-fragment-validate
description	Validate SEA spec fragments for CALM compliance, required sections, schema correctness, and cross-reference integrity.

Spec Fragment Validation

Use this skill to validate SEA specification fragments before committing changes. Ensures all specs meet quality and compliance standards.

When to Use

Invoke when:

• Creating or modifying spec files in docs/specs/
• Reviewing spec changes in a PR
• Running pre-commit validation
• Checking spec completeness

Usage

Claude invokes automatically when editing spec files, or user can invoke with:

• "Validate this spec"
• "Check spec compliance"
• "Is this spec complete?"

Validation Checks

1. YAML Frontmatter Completeness

Every spec must have valid frontmatter:

---
title: Spec Title
version: 1.0.0
status: draft|proposed|accepted|deprecated|superseded
created: YYYY-MM-DD
updated: YYYY-MM-DD
authors:
  - name: Author Name
    role: Role
---

Required fields:

• title: Brief, descriptive title
• version: Semantic version
• status: One of the allowed statuses
• created: Creation date
• updated: Last modification date
• authors: At least one author with name

2. Required Sections

Every spec must contain:

A. Context (Required)

• What problem does this solve?
• Why is this spec needed?
• What are the constraints/assumptions?

B. Requirements (Required)

• Functional requirements
• Non-functional requirements
• Acceptance criteria

C. Design/Specification (Required for technical specs)

• Architecture overview
• Data structures
• API contracts
• Implementation notes

D. Governance (For CALM specs)

• CALM boundaries
• Compliance requirements
• Validation rules

3. CALM Compliance (If Applicable)

For CALM-related specs:

• Uses @finos/calm-cli format
• Defines bounded contexts clearly
• Specifies context mappings
• Includes service contracts
• Documents business capabilities

4. Schema Validation

For YAML/JSON specs:

• Valid YAML/JSON syntax
• No trailing whitespace
• Consistent indentation
• Proper quoting of strings

5. Cross-Reference Integrity

• All [links](path/to/file.md) resolve to existing files
• All [](spec:reference) style references are valid
• No circular dependencies
• Relative paths are correct

Output Format

## Spec Validation: {spec-file}

### Frontmatter ✅/❌
{status or list of missing/invalid fields}

### Required Sections ✅/❌
{status or list of missing sections}

### CALM Compliance ✅/❌
{status or list of CALM issues}

### Schema ✅/❌
{status or list of syntax errors}

### Cross-References ✅/❌
{status or list of broken links}

### Overall Status: PASS/FAIL

### Issues Found
{detailed list of issues with file:line references}

### Recommendations
{specific fixes for each issue}

Common Issues

Missing Frontmatter

Error: No YAML frontmatter found
Fix: Add --- delimited frontmatter block at start of file

Invalid Status

Error: Status "draft" is not a valid status
Valid statuses: draft, proposed, accepted, deprecated, superseded

Broken Link

Error: Link target does not exist
File: docs/specs/unknown-spec.md
Reference: [Some Spec](docs/specs/unknown-spec.md)
Line: 42

Missing Section

Error: Required section 'Context' not found
Fix: Add ## Context section with problem description

Automated Validation

Can be run via command:

# Validate single spec
npx @sea/spec-validator docs/specs/my-spec.md

# Validate all specs
npx @sea/spec-validator docs/specs/**/*.md

# Validate and auto-fix where possible
npx @sea/spec-validator --fix docs/specs/**/*.md

Integration

This skill integrates with:

• governance-validation skill - for CALM-specific validation
• spec-guardian subagent - for pre-commit enforcement
• CI/CD - for automated validation in PRs

Constraints

• Don't auto-fix specs without user confirmation
• Preserve authorial voice and content
• Only flag structural/compliance issues, not content quality
• Allow for draft specs to be incomplete