doc-tspec-fixer_skill

Overview

This skill automates fixes for TSPEC (Test Specification) documents by reading the latest review report and applying corrective actions. It bridges review output and corrected artifacts, handling folder structure, broken links, element IDs, test case structure, and iterative improvements. Use it to reduce manual cleanup and accelerate review→fix cycles.

How this skill works

The skill locates the most recent review report for a target TSPEC, parses categorized issues, and runs a phased fixer pipeline. Phases include enforcing nested folder structure, creating missing artifacts, repairing links, normalizing element IDs, filling minimal test content, updating traceability, and handling upstream drift via tiered auto-merge. After changes it writes a fixed TSPEC and generates a fix report, optionally re-invoking the reviewer for iterative improvement.

When to use it

• After a doc-tspec-reviewer run identifies issues
• As part of an automated review→fix→review CI/CD pipeline
• Batch-fixing multiple TSPECs from review reports
• When test cases show malformed or missing structure
• When upstream SPEC changes require reconciled traceability

Best practices

• Run the reviewer before this fixer; it needs a review report as input
• Keep commits small and review auto-generated placeholders manually
• Use CI gates to re-run reviewer after fixes and limit auto-merge iterations
• Configure templates (test data, fixtures, matrix) with organization metadata before running
• Treat flagged manual items (TODO/TBD) as required follow-up work

Example use cases

• Automatically move TSPEC files into required nested folders and correct relative links
• Create placeholder test-data, fixtures, and matrix files referenced but missing
• Normalize legacy element IDs (TC-/TS-/TD-/TF-) to valid TSPEC codes
• Repair broken internal links and convert absolute paths to correct relative paths
• Insert minimal test steps, preconditions, and expected results templates for malformed test cases