name: doc-validation-rfc-37 description: > Validate documentation structure, freshness, and RFC-37 compliance using bitso-documentation-linter. Ensures docs/ folder structure (api, decisions, concepts, how-tos, runbooks) and Confluence mirroring metadata. Use when validating documentation or checking for sync issues. compatibility: All repositories with docs/ folder; requires bitso-documentation-linter metadata: version: "1.0.0" rfc: "RFC-37" linter: "bitso-documentation-linter"

RFC-37 Documentation Validation

Validates documentation structure and synchronization following RFC-37 standards.

When to use this skill

• Validating documentation structure against RFC-37
• Checking if documentation is synchronized with code
• Running documentation linting before commits
• Setting up documentation validation in CI/CD
• Fixing documentation linting violations
• Verifying Confluence mirroring configuration

Skill Contents

Sections

• When to use this skill (L19-L27)
• Quick Start (L67-L106)
• Standard Directory Structure (L107-L123)
• Documentation Validation Checks (L124-L135)
• Pre-Push Documentation Check (L136-L175)
• Available Functions (L176-L203)
• Documentation Tools by Project Type (L204-L212)
• Best Practices (L213-L234)
• References (L235-L244)
• Assets (L245-L252)
• Related Skills (L253-L259)

Available Resources

📚 references/ - Detailed documentation

• ai fixes
• confluence metadata
• go
• installation
• java
• python
• rfc 37
• typescript
• validation rules

🔧 scripts/ - Automation scripts

• check docs updated

📦 assets/ - Templates and resources

• doclinterrc.yml.template
• local-execution.md.template
• mark.toml.template

Quick Start

1. Install the linter

brew tap bitsoex/homebrew-bitso
brew install bitso-documentation-linter

See references/installation.md for alternative installation methods.

2. Create directory structure

mkdir -p docs/{decisions,how-tos,runbooks}
mkdir -p docs/my-service/{concepts,getting-started}

3. Create Confluence config

# Copy and edit the template
cp assets/mark.toml.template docs/mark.toml

See references/confluence-metadata.md for configuration details.

4. Run validation

# Basic validation
doclinter --repo-path . --verbose

# Preview Confluence tree
doclinter tree --repo-path .

# Via skills CLI
node .scripts/skills-cli.ts doc-validation-rfc-37 validate

Standard Directory Structure

docs/
├── api/                    # API documentation
│   ├── async/              # Event-driven APIs
│   ├── grpc/               # gRPC APIs
│   └── rest/               # REST APIs
├── decisions/              # Architecture Decision Records (required)
├── how-tos/                # Step-by-step guides (required)
│   └── local-execution.md  # REQUIRED for all services
├── runbooks/               # Operational procedures (required)
└── <service-name>/         # Service-specific docs
    ├── concepts/           # Architecture, design (required)
    └── getting-started/    # Quick start (required)

Documentation Validation Checks

Pre-Push Documentation Check

The system verifies 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

Via Skills CLI

node .scripts/skills-cli.ts doc-validation-rfc-37 validate
node .scripts/skills-cli.ts doc-validation-rfc-37 lint

Programmatic Usage

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

const result = await validateDocs('.', { quiet: false });

console.log('Passed:', result.passed);
console.log('Issues:', result.issues);
console.log('Warnings:', result.warnings);

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 (see directory structure above).

3. Link Related Docs

Use relative links between documentation files.

4. Keep Docs Fresh

• Run freshness checks periodically
• Update docs when APIs change
• Review docs during code reviews

References

Assets

Related Skills