doc-spec-reviewer_skill

This skill performs comprehensive SPEC content review, validating REQ coverage, interface completeness, and drift detection to ensure readiness for TASKS and

Python

9

GitHub Stars

1

Bundled Files

2 months ago

Catalog Refreshed

4 months ago

First Indexed

Readme & install

Copy the install command, review bundled files from the catalogue, and read any extended description pulled from the listing source.

Installation

Preview and clipboard use veilstrat where the catalogue uses aiagentskills.

npx veilstrat add skill vladm3105/aidoc-flow-framework --skill doc-spec-reviewer

SKILL.md18.2 KB

Overview

This skill provides comprehensive content review and quality assurance for Technical Specification (SPEC) documents. It validates YAML structure, checks REQ coverage and interface definitions, detects upstream drift, and produces a prioritized issue list plus a review score. The tool enforces mandatory drift cache behavior and flags blocking structural violations before deeper checks.

How this skill works

The reviewer loads a SPEC YAML, verifies nested folder and 13-section completeness, and runs nine focused checks (structure, REQ coverage, interfaces, thresholds, data models, error handling, placeholders, naming, drift). It computes SHA-256 hashes for files and sections to detect upstream drift, updates a mandatory .drift_cache.json atomically, and outputs a review score with categorized issues and auto-fix where safe.

When to use it

Immediately after automated SPEC generation (post doc-spec-autopilot)
After manual edits to a SPEC before downstream tasks
As a pre-check before generating TASKS or TSPEC artifacts
Regularly for periodic quality assurance of existing SPECs
When traceability to REQ/CTR must be validated and drift tracked

Best practices

Always run after any change to REQ or CTR documents to capture drift early
Keep the .drift_cache.json under version control and ensure cache_version compatibility
Resolve blocking structure errors (nested folder, filename) before other reviews
Treat placeholder detections ([TODO]/[TBD]) as highest-priority manual work items
Review and accept cached updates only after human verification of substantive upstream changes

Example use cases

Final QA gate before TASKS/TSPEC generation to ensure implementation readiness
Catching missing REQ implementations or unmapped acceptance criteria in a SPEC
Detecting changed upstream API contracts and flagging section-level drift for review
Validating that interface and method signatures are complete and implementation-ready
Ensuring threshold registry values match upstream requirements and SLAs

FAQ

A missing or invalid drift cache triggers an error (REV-D006) and initializes a new cache; the review still runs but you must resolve the cache state and commit it to enable accurate incremental drift detection.

Are any fixes applied automatically?

The skill auto-fixes only safe, structural or formatting issues where deterministic changes are available. Content issues, placeholders, and upstream drift are flagged for manual review.