doc-tspec-validator_skill

Overview

This skill validates Test Specification (TSPEC) documents against Layer 10 schema standards to ensure metadata, structure, naming, tagging, and test identifiers comply with organizational rules. It detects blocking errors, warnings, and info items, computes TASKS-Ready scores, and can run auto-fix actions for some issues. Use it to gate TSPEC artifacts before downstream generation or CI quality checks.

How this skill works

The validator parses YAML frontmatter and full Markdown content to inspect folder placement, file naming, required tags, and seven mandatory sections. It checks Document Control fields, element ID formats (TSPEC.NN.TT.SS), type-specific codes (40–43), cumulative tagging (eight required tags), coverage matrix completeness, test case I/O tables, pseudocode, and error-case documentation. Results include blocking errors, warnings, and informational suggestions and can produce a validation report or attempt safe auto-fixes.

When to use it

• After creating or modifying a TSPEC document to ensure compliance before review
• As a pre-merge or CI quality gate to block misstructured artifacts
• Before generating downstream TASKS artifacts or traceability matrices
• When auditing test coverage or validating traceability to SPEC/REQ
• To enforce naming, folder structure, and element ID conventions

Best practices

• Place each TSPEC in a nested folder under docs/10_TSPEC/{TYPE}/{TYPE}-NN_{slug}/
• Populate full YAML frontmatter with required custom_fields and tags before validation
• Use TSPEC.NN.TT.SS element IDs with the correct type code (UTEST=40, ITEST=41, STEST=42, FTEST=43)
• Include the seven required H2 sections in numbered order and a complete Document Control table
• Add all eight cumulative tags (@brd through @spec) to enable cross-document traceability
• Run the validator with --verbose and optionally --auto-fix in a controlled workflow

Example use cases

• Validate a single UTEST after drafting to verify folder, file name, and element IDs
• Run batch validation over docs/10_TSPEC/ in CI to block submissions with blocking errors
• Assess TASKS-Ready score and receive warnings when coverage or score fall below targets
• Check cumulative tagging across TSPEC and upstream SPEC/REQ artifacts for traceability
• Auto-fix trivial tag or frontmatter gaps before manual review