doc-sync

• 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

Sections

• [When to use this skill](#when-to-use-this-skill) (L16-L23)
• [Quick Start](#quick-start) (L53-L73)
• [Documentation Validation Checks](#documentation-validation-checks) (L74-L83)
• [Integration with RFC-37](#integration-with-rfc-37) (L84-L101)
• [Pre-Push Documentation Check](#pre-push-documentation-check) (L102-L141)
• [Available Functions](#available-functions) (L142-L169)
• [Documentation Tools by Project Type](#documentation-tools-by-project-type) (L170-L178)
• [Best Practices](#best-practices) (L179-L210)
• [References](#references) (L211-L219)
• [Related Skills](#related-skills) (L220-L227)
• [Documentation in This Repository](#documentation-in-this-repository) (L228-L236)

Available Resources

📚 references/ - Detailed documentation

• [go](references/go)
• [java](references/java)
• [python](references/python)
• [typescript](references/typescript)

🔧 scripts/ - Automation scripts

• [check docs updated](scripts/check-docs-updated.ts)

---

1. Check Documentation Status

```bash

# 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:

```bash

# In .git-hooks/pre-push or hooks-checks.js

# Checks if docs need updating when architecture files change

```

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

For repositories following RFC-37 documentation standards:

```bash

# 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](../rfc-37-documentation/SKILL.md) for full RFC-37 compliance.

The system can verify documentation is updated when significant files change:

Architecture Files That Trigger Doc Checks

```javascript

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

```bash

# 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"

```

The doc-sync module exports these functions:

```javascript

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

```javascript

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);

```

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

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

| Reference | Description |

|-----------|-------------|

| [references/java/javadoc-patterns.md](references/java/javadoc-patterns.md) | Java documentation patterns |

| [references/typescript/jsdoc-patterns.md](references/typescript/jsdoc-patterns.md) | TypeScript documentation patterns |

| [references/python/docstring-patterns.md](references/python/docstring-patterns.md) | Python documentation patterns |

| [references/go/godoc-patterns.md](references/go/godoc-patterns.md) | Go documentation patterns |

| Skill | Purpose |

|-------|---------|

| [rfc-37-documentation](../rfc-37-documentation/SKILL.md) | RFC-37 structure and Confluence mirroring |

| [quality-gateway](../quality-gateway/SKILL.md) | Quality gate orchestration |

| [git-hooks](../git-hooks/SKILL.md) | Pre-commit/pre-push hook setup |

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