tomevault-io Documentation Sync Check
Analyze git changes to identify documentation that may need updating. This skill compares code modifications against reference docs (docs/src/content/docs/advanced/) and package READMEs to ensure documentation stays in sync with the codebase.
Instructions
When this skill is invoked:
- Read the detailed agent instructions from
.claude/agents/docs-check/instructions.md - Gather the current changes using git diff
- Map code changes to relevant documentation
- Analyze whether documentation needs updating
- Provide a structured report with findings
Usage
/docs-check # Check all uncommitted changes
/docs-check --staged # Check only staged changes
/docs-check <commit> # Check changes in a specific commit
/docs-check <base>..<head> # Check changes between commits
Process
Step 1: Gather Changes
Based on arguments:
- No args:
git diff HEAD(all uncommitted changes) --staged:git diff --staged<commit>:git show <commit><base>..<head>:git diff <base>..<head>
Also run git diff --name-only (with appropriate flags) to get the list of changed files.
Step 2: Categorize Changed Files
Group changes by their documentation relevance:
| File Pattern | Related Documentation |
|---|---|
packages/*/src/** |
TSDoc on exports, package README, relevant reference docs in docs/src/content/docs/advanced/ |
examples/** |
Package READMEs, CLAUDE.md |
| Exports/public API | TSDoc on exports, package README, CLAUDE.md |
Look in docs/src/content/docs/advanced/ to identify which reference docs are relevant for a given package or subsystem.
Step 3: Analyze Documentation Impact
For each category of changes, determine:
- API Changes: New exports, renamed functions, changed signatures
- Behavioral Changes: Modified algorithms, new features, changed defaults
- Structural Changes: New files, moved code, renamed modules
- Configuration Changes: New options, changed config shapes
Step 4: Check Documentation
Read relevant documentation files and compare against code changes:
- Are new features/APIs documented?
- Do examples still match the current API?
- Are behavioral descriptions still accurate?
- Is terminology consistent with code?
Step 5: Generate Report
Provide a structured report categorizing findings by urgency.
Output Format
# Documentation Sync Check
## Summary
[Brief overview of changes and documentation status]
## Changes Analyzed
- [List of changed files grouped by area]
## Documentation Updates Required
### Must Update
[Documentation that is definitely out of sync - factually incorrect, missing new features, wrong API signatures]
### Should Review
[Documentation that may need updating - behavioral changes, new edge cases, terminology]
### Already Up to Date
[Documentation that was checked and appears current]
## Specific Recommendations
### [doc-file-path]
- **Issue**: [What's wrong or missing]
- **Code Reference**: [Which code change necessitates this]
- **Suggested Action**: [What to update]
## No Documentation Impact
[Changes that don't require documentation updates and why]
Severity Definitions
MUST UPDATE: Documentation is factually incorrect or missing critical information
- Incorrect API signatures or examples
- Missing documentation for new public APIs
- Wrong behavioral descriptions
SHOULD REVIEW: Documentation may be stale or incomplete
- Changed default values or behaviors
- New edge cases or limitations
- Terminology drift
NO IMPACT: Changes that don't affect documentation
- Internal refactoring with no API changes
- Test-only changes
- Bug fixes that don't change documented behavior
Converted and distributed by TomeVault — claim your Tome and manage your conversions.