doc-ctr-reviewer_skill

This skill reviews CTR documents for cross-file consistency, OpenAPI compliance, and upstream alignment, delivering a final QA score and actionable issue list.

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-ctr-reviewer

SKILL.md15.4 KB

Overview

This skill performs comprehensive content review and quality assurance for Data Contract (CTR) documents. It validates contract completeness, ensures markdown and YAML files are synchronized, checks OpenAPI compliance, and detects upstream REQ drift that requires manual attention. The output is a review report with a score, categorized issues, and optional auto-fixes for safe changes.

How this skill works

The reviewer loads CTR files (MD + YAML when available), enforces nested folder structure, then runs a sequence of checks: dual-file consistency, OpenAPI validation, REQ trace alignment, endpoint coverage, security definitions, placeholder detection, naming compliance, and upstream drift detection using a mandatory drift cache. It classifies findings by severity, attempts auto-fixes where safe, updates the drift cache, and generates a versioned review report with a numerical score and recommendations.

When to use it

Immediately after CTR generation or after running the autopilot pipeline Phase 4 validator
After manual edits to a CTR to verify content consistency before SPEC generation
Before running downstream SPEC automation to catch blocking issues early
When external APIs or upstream REQ documents have changed
For periodic quality checks across CTRs to detect stale traces and placeholders

Best practices

Always run after structural validation to ensure the nested folder rule is satisfied
Keep both .md and .yaml files in sync; treat diffs as actionable items
Commit the mandatory drift cache into the CTR folder so change detection persists across sessions
Address Error severity items first (structure, missing endpoints, critical drift) before lower-severity warnings
Use the generated report and versioning to track review progress and regressions

Example use cases

Final QA gate after automated CTR creation to produce a SPEC-ready contract
Detecting and flagging upstream REQ changes that might invalidate interface assumptions
Finding and replacing placeholders or [TODO] markers before handoff to implementation
Verifying OpenAPI 3.x compliance for downstream tooling that consumes the YAML
Generating a documented review history and score comparisons across multiple review runs

FAQ

The skill regenerates a new drift cache file in the CTR folder, reports the event, and treats affected references as uncached until hashes are computed.

Can the reviewer auto-fix issues?

Safe, deterministic fixes (formatting, simple sync) are applied automatically when available. Content or policy changes are flagged for manual review and not auto-fixed.