doc-validation-rfc-37_skill

Overview

This skill validates documentation structure, freshness, and RFC-37 compliance using the bitso-documentation-linter. It ensures the docs/ folder contains the required sections (api, decisions, concepts, how-tos, runbooks) and that Confluence mirroring metadata is present and correct. Use it to catch missing docs, broken links, or sync issues before merging or releasing. It integrates with CI and local pre-push checks for automated enforcement.

How this skill works

The skill runs a set of checks provided by bitso-documentation-linter and project scripts: README presence, broken internal links, API docs detection, freshness comparisons between docs and code, RFC-37 directory structure validation, and Confluence mark.toml checks. It can run via the CLI, programmatic JS imports, or as part of CI pipelines. When architecture files change, the pre-push logic enforces updates to specific documentation targets or allows an explicit skip flag.

When to use it

• Validate docs/ structure and RFC-37 compliance before PRs or releases
• Check documentation freshness relative to code changes
• Run as a CI check to prevent regressions in documentation
• Pre-push verification when architecture or workflow files change
• Verify Confluence mirroring configuration and mark.toml correctness

Best practices

• Update documentation in the same PR that changes code to keep them in sync
• Follow the RFC-37 directory layout: api, decisions, how-tos, runbooks, and service folders
• Include local-execution.md for services and keep README.md as the single source of truth
• Use relative links and run broken-link checks regularly
• Integrate the linter into CI and pre-push hooks to catch issues early

Example use cases

• Run doclinter locally before creating a pull request to catch missing README or broken links
• Add the validation step to CI to block merges when RFC-37 structure or Confluence metadata are invalid
• Automate a pre-push check that triggers when architecture files are modified
• Use the programmatic API to build a dashboard that reports documentation freshness and issues
• Preview the Confluence tree to verify parent IDs and export structure before syncing