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

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.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

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, skills
• concepts/ - Architecture and design concepts
• how-tos/ - Step-by-step guides
• mcp/ - MCP configuration docs
• overview.md - Main entry point