doc-tspec-reviewer_skill

Overview

This skill performs comprehensive content review and quality assurance for TSPEC documents. It validates test coverage across UTEST/ITEST/STEST/FTEST, checks SPEC alignment, verifies test case completeness, and flags issues that need manual attention. The output is a review score plus a categorized issue list and optional auto-fixes for trivial problems.

How this skill works

The reviewer loads a TSPEC file, enforces structure rules, and runs a sequence of checks: coverage targets, SPEC traceability, test case completeness, test data and environment definitions, edge-case coverage, placeholder detection, naming compliance, and upstream drift detection. A mandatory drift cache (.drift_cache.json) tracks upstream SPEC hashes; the skill initializes, validates, and updates that cache as part of the workflow. Results include a pass/warn/fail score, detailed error codes, and recommended actions.

When to use it

• Immediately after TSPEC generation (post doc-tspec-autopilot) to validate readiness
• After manual edits to ensure edits didn’t introduce coverage or traceability gaps
• Before starting test implementation as the final QA gate
• When auditing test coverage completeness across UTEST/ITEST/STEST/FTEST
• For periodic quality checks to detect upstream SPEC drift and stale TSPECs

Best practices

• Run structure compliance first; fix blocking structure errors before other checks
• Keep the drift cache committed and up to date to detect upstream changes reliably
• Address all REV-STR and REV-TC errors before implementation to avoid rework
• Use the named error codes in issue triage and PR descriptions for clarity
• Treat REV-D00* warnings seriously—review upstream changes and update tests

Example use cases

• Validate a generated TSPEC-03 file to ensure UTEST coverage >= 80% and SPEC methods are traced
• Scan a directory of TSPECs to initialize drift cache and identify stale specs after a SPEC release
• Pre-implementation gate: fail TSPECs with missing test steps or placeholder TODOs
• Periodic audit: run the reviewer to produce a prioritized issue list for the QA backlog
• CI integration: fail pipeline when review score < threshold or critical upstream drift detected