doc-validation-rfc-37

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

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
Confluence metadata	Validates mark.toml and parent IDs	Error
Local execution	Checks for required local-execution.md	Error

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

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

Reference	Description
references/rfc-37.md	RFC-37 summary and requirements
references/validation-rules.md	All 10 linter rules with examples
references/confluence-metadata.md	Confluence config (mark.toml, metadata)
references/installation.md	Linter installation guide
references/ai-fixes.md	AI-assisted documentation fixes

Assets

Asset	Description
assets/mark.toml.template	Confluence config template
assets/doclinterrc.yml.template	Linter config template
assets/local-execution.md.template	Local execution doc template

Related Skills

Skill	Purpose
doc-generation-rfc-37	AI-assisted documentation generation
quality-checks	Quality gate orchestration
git-hooks	Pre-commit/pre-push hook setup