doc-sync

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

• go
• java
• python
• typescript

🔧 scripts/ - Automation scripts

• check docs updated

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

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.md
• docs/ai-ide-management/how-tos/targeting-and-inheritance.md
• docs/ai-ide-management/overview.md
• README.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

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

Related Skills

Documentation in This Repository

For ai-code-instructions documentation, see docs/ai-ide-management/:

• catalogues/ - Catalogues of rules, commands, MCP, skills
• concepts/ - Architecture and design concepts
• how-tos/ - Step-by-step guides
• mcp/ - MCP configuration docs
• overview.md - Main entry point