doc-spec-autopilot_skill

Overview

This skill automates generation of implementation-ready SPEC YAML files from REQ and optional CTR sources and provides TASKS-Ready scoring. It runs readiness checks, generates the full 13-section SPEC structure, validates TASKS readiness, and drives an iterative review-and-fix cycle until quality targets are met. The output is a validated SPEC ready for downstream TSPEC and TASKS generation.

How this skill works

The autopilot detects input type (SPEC, REQ, or CTR) and chooses generate or review mode. For generation it extracts implementation details, maps them to the 13 required SPEC sections, and writes a structured YAML including interfaces, data models, validation rules, and traceability. It runs automated validators and a quality advisor, computes a TASKS-Ready score, and invokes a review-and-fix loop (doc-spec-reviewer → doc-spec-fixer) until thresholds are met. Finalized SPECs include traceability updates and TASKS-Ready scoring metadata.

When to use it

• You have REQ or CTR documents and need a production-grade SPEC YAML for implementation.
• You already have a SPEC and want an automated quality review and TASKS-Ready validation.
• You want consistent 13-section SPECs with three-level interface coverage (external/internal/classes).
• You need automated traceability linking to BRD/PRD/REQ/CTR and @threshold references.
• You require an iterative fix cycle to reach target quality scores before TASKs generation.

Best practices

• Provide well-structured REQ/CTR inputs so upstream parsing yields accurate implementation details.
• Ensure REQ SPEC-Ready score >= target or allow autopilot auto-fixes for simple issues before generation.
• Keep element IDs compliant with the SPEC.NN.TT.SS naming convention to avoid legacy conversion work.
• Use the max_iterations and target_score parameters to control the review/fix loop behavior.
• Review and approve the generated authors/reviewers and threshold references before marking SPEC final.

Example use cases

• Generate SPEC-05 from CTR-05 when no SPEC exists, producing full YAML with interfaces and data models.
• Run review mode on SPEC-03 to produce a review report, fix cycle, and TASKS-Ready score improvement.
• Batch process multiple REQ inputs (REQ-01, REQ-02) to create or validate multiple SPECs in docs/09_SPEC.
• Convert legacy REQ element IDs into SPEC-compliant IDs and replace hardcoded thresholds with @threshold references.
• Produce a SPEC that includes Pydantic models, OpenAPI-style external API specs, and a traceability matrix for delivery handoffs.