Docs Check Skill
Relevant source files
The following files were used as context for generating this wiki page:
The docs-check skill is a utility designed to analyze code changes within a git repository and identify which documentation files may require updates. It operates by comparing the current state of the repository (including staged and uncommitted files) against the main branch, categorizing the changes, and suggesting relevant documentation for review. This skill is a key component of the Docs-as-Code approach, ensuring that documentation remains synchronized with the evolving codebase.
The primary entry point is the check-docs.sh script. Its purpose is to automate the initial step of documentation maintenance by flagging potential impacts, which can then be addressed using the Docs Write Skill.
Sources: skills/docs-check/SKILL.md, skills/docs-check/scripts/check-docs.sh, skills/README.md:15-16
Core Functionality
The skill is executed via a bash script that performs the analysis. It is intended to be run after making code changes and before committing to a pull request.
Sources: skills/docs-check/SKILL.md:1-4
Invocation
The script can be run from the command line. It supports several arguments to control its output.
# Basic usage
bash skills/docs-check/scripts/check-docs.sh
# Verbose mode for detailed debugging output
bash skills/docs-check/scripts/check-docs.sh --verbose
Sources: skills/docs-check/SKILL.md:21-29, skills/docs-check/scripts/check-docs.sh:10-24
Command-Line Arguments
| Argument | Alias | Description |
|---|---|---|
--verbose | -v | Shows detailed debugging output during script execution. |
--help | -h | Displays a help message with usage instructions. |
Sources: skills/docs-check/scripts/check-docs.sh:10-24
Analysis Workflow
The check-docs.sh script follows a multi-step process to analyze changes and provide recommendations. It begins by identifying all changed files and then categorizes them based on predefined patterns to suggest relevant documentation.
The following diagram illustrates the high-level workflow of the check-docs.sh script.
1. Change Detection
The script first determines the repository's main branch (either main or master). It then uses git diff to compile a list of all files that have changed between the main branch and the current HEAD, including both staged and uncommitted files. If no changes are detected, the script exits.
Sources: skills/docs-check/scripts/check-docs.sh:44-67
2. File Caching and Separation
To work efficiently, the script performs a one-time scan of the repository to find and cache all potential documentation files (e.g., .md, .puml). It then separates the list of changed files into two groups: documentation files that were already modified and code files that need analysis.
Sources: skills/docs-check/scripts/check-docs.sh:73-86
3. Change Categorization
This is the core logic of the skill. The script iterates through the changed code files and matches their paths against a series of regular expression patterns to assign them to a category. For each category, it suggests relevant documentation files or directories to review.
The following table details the patterns used for categorization and the corresponding documentation suggestions.
| Category | File Patterns (Regex) | Suggested Doc Files/Patterns |
|---|---|---|
| Database/Schema | (schema|db|database|migration|model) | (db|database|schema) |
| API | (api|router|route|endpoint|trpc|graphql|rest) | (api|workflow|endpoint|route) |
| Component/UI | (component|ui|view|page|layout|template) | (component|ui|feature|guide) |
| Configuration | (config|\.env|env\.js|\.gitignore|package\.json|...|tsconfig|eslint|prettier) | (config|setup|install|environment) |
| Authentication/Security | (auth|login|session|security|permission|role) | (auth|security|login|session) |
| Hook/Utility | (hook|util|lib|helper|service) | (util|helper|api|guide) |
| Email/Template | (email|mail|template|notification) | (email|mail|notification|template) |
| Test | (test|spec|__tests__|\.test\.|\.spec\.) | (test|testing|spec) |
| Style/CSS | (\.css|\.scss|\.sass|\.less|style) | (style|css|theme|design) |
| Other | Any file not matching the above categories. | README.md, SETUP.md, CONTRIBUTING.md, files in .docs/ |
Sources: skills/docs-check/scripts/check-docs.sh:122-243
4. Output Generation
After analysis, the script generates a report in the console. The report includes:
- A list of documentation files that were already updated.
- A breakdown of changed code files by category.
- For each category, a list of suggested documentation files to check.
- A final summary with statistics on the number of files changed.
- A set of universal guidelines and a review process to help the user update the documentation effectively.
Sources: skills/docs-check/scripts/check-docs.sh:89-100, 245-305
Integration with Other Skills
The docs-check skill is designed to be the first step in the documentation update workflow. Its output directly informs the next actions, which typically involve the docs-write skill.
This diagram shows how docs-check initiates the documentation workflow, which relies on documentation-guide.md for standards and is executed via the docs-write skill.
Sources: skills/docs-check/SKILL.md:31-35, 40-47, skills/docs-write/SKILL.md:1-6
A critical part of the workflow is referencing references/documentation-guide.md. The docs-check skill mandates that this guide be loaded to validate the structure of existing documentation and to guide any new updates, ensuring consistency across the project.
Sources: skills/docs-check/SKILL.md:40-47, skills/docs-check/references/documentation-guide.md
Conclusion
The docs-check skill serves as an automated gatekeeper for documentation quality. By systematically analyzing code changes and providing targeted recommendations, it bridges the gap between development and documentation. This ensures that documentation does not become stale and accurately reflects the current state of the software, which is essential for maintainability and onboarding new developers.