sync-docs

The sync-docs skill is a specialized automation tool designed for software engineers to maintain high-quality, up-to-date documentation. It serves as an orchestration engine that analyzes the relationship between source code and project documentation, ensuring that README files, changelogs, and technical docs reflect the actual state of the codebase. By integrating with Git and leveraging static analysis tools like repo-map, it identifies discrepancies that often emerge during rapid development cycles, such as removed function exports, outdated code snippets in tutorials, or import path changes. The skill is intended for use during pre-pull request reviews, release preparation, or following significant refactoring tasks to ensure technical debt does not accumulate in project artifacts.

• Automated discovery of related documentation based on changed files and file patterns like README.md and CHANGELOG.md.

• Version validation by comparing project metadata in package.json against documented versions.

• Export analysis to detect code symbols present in documentation that no longer exist in the implementation, effectively finding stale references.

• CHANGELOG maintenance by scanning for Unreleased sections and verifying commit message alignment with recorded changes.

• Intelligent fallback mechanisms, defaulting to regex-based detection if advanced AST tools like ast-grep are not installed.

• Structured reporting of findings, providing actionable feedback without making unauthorized direct modifications, allowing developers to review changes before applying.

• Users should invoke this skill using the syntax: sync-docs [report|apply] [--scope=all|recent|before-pr] [--include-undocumented].

• The default scope focuses on changes since the last commit to main, which is optimized for quick checks during active development sessions.

• The --include-undocumented flag is useful for uncovering public API surface areas that lack accompanying technical documentation.

• While the tool provides an apply mode, it is designed to operate within a safety-first architecture where the orchestrator manages the final application of fixes.

• Constraints: Effective symbol detection is significantly enhanced by having repo-map.json initialized; users may be prompted to install ast-grep to achieve maximum accuracy in larger, more complex repositories.