doc-sys-fixer_skill

This skill fixes SYS documents by applying review reports to correct structure, links, IDs, and content through automated iterative improvements.

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

SKILL.md28.4 KB

Overview

This skill automates fixes for SYS (System Design Specification) documents by reading the latest review report and applying corrective actions. It bridges review findings to concrete edits—fixing structure, links, element IDs, missing files, content placeholders, references, and upstream drift. It supports iterative Review → Fix → Review cycles and can be integrated into CI/CD pipelines.

How this skill works

The skill locates the most recent review report for a target SYS, parses categorized issues, and executes a phased fix pipeline. Phases run in order: enforce nested folder structure, create missing placeholder files, repair broken links, normalize element IDs, address simple content gaps, update traceability references, and perform tiered auto-merges for upstream ADR drift. After changes it writes a fix report and can re-invoke the reviewer for additional iterations.

When to use it

After doc-sys-reviewer produces a review report
As part of an iterative Review → Fix → Review cycle
In CI/CD pipelines as a quality gate to auto-resolve known issues
When applying batch fixes across multiple SYS documents
When links, IDs, or missing files block documentation builds

Best practices

Always run doc-sys-reviewer first and pass the generated report to this skill
Keep a backup or VCS commit before running fixes so manual review is possible
Limit automated auto-merges to low-change tiers; review Tier 3 actions manually
Provide project naming and element-ID conventions (doc-naming) to reduce ambiguous replacements
Use the skill to fix mechanical issues; flag placeholders and TODOs for human completion

Example use cases

Move a monolithic SYS into the required nested folder structure and update relative links
Create missing component or interface placeholders referenced by SYS pages to resolve broken links
Convert legacy element IDs to valid SYS type codes across a document set
Auto-fix internal broken links and convert absolute paths to correct relative paths
Detect upstream ADR changes and apply tiered auto-merge with changelog and version bump

FAQ

No. Placeholders like [TODO] or [TBD] are flagged for manual completion. The skill inserts defaults for date, status, and version but not substantive content.

How does upstream ADR drift get handled?

Upstream changes are measured as a change percentage. Small changes are auto-merged (Tier 1), moderate changes include detailed changelogs (Tier 2), and large changes trigger archive/regeneration workflows requiring manual review (Tier 3).