doc-spec-fixer_skill

This skill automates fixing SPEC documents by reading review reports and applying structured corrections across structure, links, IDs, and content.

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-fixer

SKILL.md28.2 KB

Overview

This skill automates fixes for SPEC (Specification) documents by reading the latest review report and applying corrective actions. It repairs folder structure, YAML and schema issues, broken links, missing files, element IDs, content placeholders, and handles upstream drift with tiered auto-merge. The skill produces an updated SPEC and a fix report to support iterative Review -> Fix -> Review cycles.

How this skill works

The skill finds the most recent review report for a given SPEC, parses and categorizes issues, then runs a sequence of fix phases from structure repairs to upstream drift resolution. It applies deterministic fixes (move/rename files, update relative links, repair YAML, create placeholders) and logs fixes in a generated fix report. Optionally it can re-invoke the reviewer to iterate until quality thresholds are met.

When to use it

After running doc-spec-reviewer to address reported issues
As part of an automated CI/CD quality gate for SPECs
When SPEC YAML blocks are malformed or have invalid element IDs
To create placeholder files referenced but missing in a SPEC
When upstream REQ/CTR drift needs automated merge or traceability updates

Best practices

Run doc-spec-reviewer first so fixes target reported issues
Keep repository permissions and backups before automated moves/renames
Review flagged manual items (TODO/TBD) after auto-fixes
Set iteration limits and quality thresholds for automatic re-review
Integrate with doc-naming, doc-req and doc-ctr for consistent IDs and trace links

Example use cases

Move and reorganize a SPEC file into the required nested folder and update all upstream relative links
Repair malformed YAML blocks, fix duplicate keys, and insert missing required fields with placeholders
Create missing schema or config files referenced by the SPEC using templates
Convert legacy or invalid element IDs into normalized YAML-path style IDs
Detect upstream REQ changes and apply a tiered auto-merge (patch/minor/major) with changelog

FAQ

No. It flags placeholders for manual completion and can add minimal template content, but human review is required for substantive content.

Will the skill change file paths or names automatically?

Yes. Structure fixes create nested folders and rename/move files as required, and update relative links. Backups are recommended before running.