doc-ctr-autopilot_skill

Overview

This skill automates generation and review of Data Contracts (CTR) from REQ interface specifications, producing paired markdown and YAML contract files with SPEC-Ready scoring. It detects which REQ modules require CTRs, generates nested-folder dual-file contracts, validates them, and manages an iterative review-and-fix cycle to reach quality thresholds. The pipeline enforces traceability tags and OpenAPI-compliant YAML output.

How this skill works

The autopilot parses input IDs (REQ-NN or CTR-NN) to decide whether to generate a missing CTR or review an existing one. For REQ inputs it analyzes Sections 3 and 4 to extract interface definitions and data schemas, runs readiness checks, then emits CTR-NN.md and CTR-NN.yaml inside a nested folder. Generated CTRs are validated with SPEC-Ready scoring and passed through review/fix iterations until quality gates (typically ≥90%) are met.

When to use it

• When a REQ document exposes external-facing APIs, webhooks, streaming, or agent-to-agent endpoints.
• When you need consistent dual-file contracts (human docs + machine OpenAPI YAML) organized per module.
• When you want automated SPEC-Ready validation and a formal review/fix loop for contracts.
• When onboarding or maintaining API surface area across many modules to keep traceability.
• When migrating interface specs into a standardized contract repository for downstream automation.

Best practices

• Run Phase 0 CTR requirement analysis first to avoid generating unnecessary contracts.
• Ensure REQ SPEC-Ready score ≥90% and Section 4 interface details are complete before generation.
• Always use nested folder naming (CTR-NN_slug/) so md, yaml, review and fix artifacts stay grouped.
• Include all required cumulative tags (@brd, @prd, @ears, @bdd, @adr, @sys, @req) for traceability.
• Iterate review/fix cycles until validator and reviewer scores meet the ≥90% quality gate.

Example use cases

• Generate CTR-01 for an authentication REQ that defines POST /api/v1/auth/login and token flows.
• Create contracts for SSE/chat endpoints discovered in a REQ to support streaming API clients.
• Review and re-validate an existing CTR folder after schema drift or API changes.
• Batch-generate CTRs for multiple REQ inputs, producing paired .md and .yaml files per module.
• Integrate contract generation into a CI pipeline to enforce OpenAPI validation and error catalogs.