Doc Sync
doc-sync
Validates documentation is synchronized with code changes. Integrates with RFC-37 doclinter for structure validation and pre-push hooks to enforce documentation updates. Use after making significant code changes or when documentation gaps exist.
SKILL.md
Full skill instructions
Doc Sync
This skill ensures documentation stays synchronized with code changes. It provides validation tools, pre-push checks, and integration with RFC-37 documentation standards.
When to use this skill
- After making code changes that affect architecture or APIs
- When documentation may be out of sync with code
- During code review to verify documentation completeness
- To check for broken links in documentation
- When setting up documentation validation in a repository
Skill Contents
Sections
- When to use this skill (L16-L23)
- Quick Start (L53-L73)
- Documentation Validation Checks (L74-L83)
- Integration with RFC-37 (L84-L101)
- Pre-Push Documentation Check (L102-L141)
- Available Functions (L142-L169)
- Documentation Tools by Project Type (L170-L178)
- Best Practices (L179-L210)
- References (L211-L219)
- Related Skills (L220-L227)
- Documentation in This Repository (L228-L236)
Available Resources
📚 references/ - Detailed documentation
🔧 scripts/ - Automation scripts
Quick Start
1. Check Documentation Status
# Via skills CLI
node .scripts/skills-cli.ts doc-sync validate
# Or directly
node -e "import('./.scripts/lib/skills/doc-sync.ts').then(m => m.validateDocs('.'))"
2. Pre-Push Hook Integration
Add documentation validation to your pre-push hook:
# In .git-hooks/pre-push or hooks-checks.js
# Checks if docs need updating when architecture files change
Documentation Validation Checks
| Check | What It Does | Severity |
|---|---|---|
| README presence | Verifies README.md exists | Error |
| Broken links | Checks internal markdown links | Warning |
| API docs | Looks for generated API documentation | Info |
| Freshness | Compares doc timestamps to code | Warning |
| RFC-37 structure | Validates docs/ folder structure | Error |
Integration with RFC-37
For repositories following RFC-37 documentation standards:
# Install the linter
brew tap bitsoex/homebrew-bitso
brew install bitso-documentation-linter
# Run RFC-37 validation
doclinter --repo-path . --verbose
# Preview Confluence structure
doclinter tree --repo-path .
See the rfc-37-documentation skill for full RFC-37 compliance.
Pre-Push Documentation Check
The system can verify documentation is updated when significant files change:
Architecture Files That Trigger Doc Checks
const ARCHITECTURE_FILES = [
'technology-hierarchy.json',
'repo-overrides.json',
'managed-paths.json',
'.scripts/convert-rules.ts',
'.scripts/targeting.ts',
'.scripts/safe-sync.ts',
'.scripts/ci-distribute.ts',
'.github/workflows/ci.yaml'
];
Expected Documentation Updates
When architecture files change, update one of:
docs/ai-ide-management/concepts/architecture.mddocs/ai-ide-management/how-tos/targeting-and-inheritance.mddocs/ai-ide-management/overview.mdREADME.md
Skipping the Check
# For a single commit (when docs truly aren't needed)
AI_AGENTS_SKIP_DOCS_CHECK=1 git commit -m "chore: minor config tweak"
# Or document why in commit message
git commit -m "fix: typo in config
No docs update needed - cosmetic change only"
Available Functions
The doc-sync module exports these functions:
import {
validateDocs, // Run all documentation checks
checkReadme, // Verify README presence
checkBrokenLinks, // Find broken internal links
checkApiDocs, // Look for API documentation
checkFreshness, // Compare doc/code timestamps
DOC_TOOLS // Recommended tools by project type
} from './.scripts/lib/skills/doc-sync.ts';
Example Usage
import { validateDocs } from './.scripts/lib/skills/doc-sync.ts';
const result = await validateDocs('.', { quiet: false });
console.log('Passed:', result.passed);
console.log('Issues:', result.issues);
console.log('Warnings:', result.warnings);
console.log('Recommendations:', result.recommendations);
Documentation Tools by Project Type
| Project | Tools | Commands |
|---|---|---|
| Java/Gradle | Javadoc, Checkstyle | ./gradlew javadoc |
| Node.js | TypeDoc, JSDoc, markdownlint | npx typedoc, npx markdownlint "**/*.md" |
| Python | Sphinx, pydocstyle, MkDocs | sphinx-build, pydocstyle |
| Go | godoc, go doc | go doc -all |
Best Practices
1. Document As You Code
- Update docs in the same PR as code changes
- Use the pre-push hook to catch missing updates
- Keep README.md as the single source of truth
2. Structure Documentation
Follow RFC-37 structure for consistency:
docs/
├── decisions/ # ADRs (Architecture Decision Records)
├── how-tos/ # Step-by-step guides
├── runbooks/ # Operational procedures
└── {service}/ # Service-specific docs
├── concepts/ # Architecture, design
└── getting-started/
3. Link Related Docs
Use relative links between documentation files. For example, link from one reference file to another using relative paths like ./other-file.md or ../other-folder/file.md.
4. Keep Docs Fresh
- Run freshness checks periodically
- Update docs when APIs change
- Review docs during code reviews
References
| Reference | Description |
|---|---|
| references/java/javadoc-patterns.md | Java documentation patterns |
| references/typescript/jsdoc-patterns.md | TypeScript documentation patterns |
| references/python/docstring-patterns.md | Python documentation patterns |
| references/go/godoc-patterns.md | Go documentation patterns |
Related Skills
| Skill | Purpose |
|---|---|
| rfc-37-documentation | RFC-37 structure and Confluence mirroring |
| quality-gateway | Quality gate orchestration |
| git-hooks | Pre-commit/pre-push hook setup |
Documentation in This Repository
For ai-code-instructions documentation, see docs/ai-ide-management/:
catalogues/- Catalogues of rules, commands, MCP, skillsconcepts/- Architecture and design conceptshow-tos/- Step-by-step guidesmcp/- MCP configuration docsoverview.md- Main entry point