RFC-37 Documentation Validation Skill

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

Available Resources

📚 references/ - Detailed documentation

🔧 scripts/ - Automation scripts

check docs updated

📦 assets/ - Templates and resources

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 |

Agent Skills: RFC-37 Documentation Validation

Install this agent skill to your local

Skill Files