doc-req-fixer_skill

Overview

This skill automates fixes for Requirements Specification (REQ) documents by reading the latest review report and applying corrective actions. It closes the loop between review findings and an updated REQ, producing a fixed REQ and a fix report for iterative Review→Fix cycles. The skill targets structural problems, broken links, element ID normalization, missing files, content defaults, and traceability updates.

How this skill works

The skill scans the REQ path, locates the latest review report, parses categorized issues, and runs a phased fix pipeline. Phases run in order: enforce nested folder structure, create missing files from templates, repair broken links, convert element IDs to valid REQ codes, autofill or flag content gaps, update traceability references, and attempt upstream merges for SYS drift. Each change is recorded and a fix report is generated; the reviewer can optionally re-run the reviewer tool for new iterations.

When to use it

• After running doc-req-reviewer to address reported issues
• As part of an automated CI/CD quality gate to remediate common faults
• When batch-applying fixes across multiple REQ documents
• To create placeholder files referenced but missing in the repo
• During iterative improvement cycles before manual stakeholder sign-off

Best practices

• Always run the reviewer first; fixes rely on a valid review report
• Review Phase 0 structural moves carefully—folder moves update relative links
• Limit automated content fills to defaults; flag TODO/TBD items for manual completion
• Keep a copy of the original REQ before auto-moves or large rewrites
• Re-run the reviewer after fixes and loop until score threshold or max iterations

Example use cases

• Fix a REQ file that was committed at docs/07_REQ/REQ-01.md by moving it into the required nested folder and updating links
• Auto-create REQ-00_INDEX.md and REQ-00_GLOSSARY.md when referenced but missing
• Resolve broken cross-layer links from REQ to SYS, CTR, or SPEC and convert absolute paths to relative
• Normalize legacy IDs like FR-123 or REQ.NN.13.SS into valid REQ type codes (01,05,06,27)
• Autofill missing metadata (Status: Draft, Priority: P2, Version: 0.1) and flag placeholders for manual follow-up