home / skills / bitsoex / bitso-java / doc-validation-rfc-37

doc-validation-rfc-37 skill

safe

This skill validates RFC-37 compliant documentation structure and synchronization, ensuring docs folders mirror code and Confluence metadata for reliable

npx playbooks add skill bitsoex/bitso-java --skill doc-validation-rfc-37

Review the files below or copy the command above to add this skill to your agents.

Files (14)

SKILL.md

8.5 KB

---
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](https://bitsomx.atlassian.net/wiki/spaces/BAB/pages/4485840987/RFC-37+Service+documentation+standardization) 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](#when-to-use-this-skill) (L19-L27)
- [Quick Start](#quick-start) (L67-L106)
- [Standard Directory Structure](#standard-directory-structure) (L107-L123)
- [Documentation Validation Checks](#documentation-validation-checks) (L124-L135)
- [Pre-Push Documentation Check](#pre-push-documentation-check) (L136-L175)
- [Available Functions](#available-functions) (L176-L203)
- [Documentation Tools by Project Type](#documentation-tools-by-project-type) (L204-L212)
- [Best Practices](#best-practices) (L213-L234)
- [References](#references) (L235-L244)
- [Assets](#assets) (L245-L252)
- [Related Skills](#related-skills) (L253-L259)

### Available Resources

**📚 references/** - Detailed documentation
- [ai fixes](references/ai-fixes.md)
- [confluence metadata](references/confluence-metadata.md)
- [go](references/go)
- [installation](references/installation.md)
- [java](references/java)
- [python](references/python)
- [rfc 37](references/rfc-37.md)
- [typescript](references/typescript)
- [validation rules](references/validation-rules.md)

**🔧 scripts/** - Automation scripts
- [check docs updated](scripts/check-docs-updated.ts)

**📦 assets/** - Templates and resources
- [doclinterrc.yml.template](assets/doclinterrc.yml.template)
- [local-execution.md.template](assets/local-execution.md.template)
- [mark.toml.template](assets/mark.toml.template)

---

## Quick Start

### 1. Install the linter

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

See [references/installation.md](references/installation.md) for alternative installation methods.

### 2. Create directory structure

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

### 3. Create Confluence config

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

See [references/confluence-metadata.md](references/confluence-metadata.md) for configuration details.

### 4. Run validation

```bash
# 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

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

## Available Functions

### Via Skills CLI

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

### Programmatic Usage

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

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](references/rfc-37.md) | RFC-37 summary and requirements |
| [references/validation-rules.md](references/validation-rules.md) | All 10 linter rules with examples |
| [references/confluence-metadata.md](references/confluence-metadata.md) | Confluence config (mark.toml, metadata) |
| [references/installation.md](references/installation.md) | Linter installation guide |
| [references/ai-fixes.md](references/ai-fixes.md) | AI-assisted documentation fixes |

## Assets

| Asset | Description |
|-------|-------------|
| [assets/mark.toml.template](assets/mark.toml.template) | Confluence config template |
| [assets/doclinterrc.yml.template](assets/doclinterrc.yml.template) | Linter config template |
| [assets/local-execution.md.template](assets/local-execution.md.template) | Local execution doc template |

## Related Skills

| Skill | Purpose |
|-------|---------|
| [doc-generation-rfc-37](.claude/skills/doc-generation-rfc-37/SKILL.md) | AI-assisted documentation generation |
| [quality-checks](.claude/skills/quality-checks/SKILL.md) | Quality gate orchestration |
| [git-hooks](.claude/skills/git-hooks/SKILL.md) | Pre-commit/pre-push hook setup |
<!-- AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY -->
<!-- Source: bitsoex/ai-code-instructions → global/skills/doc-validation-rfc-37/SKILL.md -->
<!-- To modify, edit the source file and run the distribution workflow -->

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

FAQ

How do I skip the documentation check for a trivial commit?

Set AI_AGENTS_SKIP_DOCS_CHECK=1 for a single commit or state in the commit message that no docs update is needed.

How can I run the validator programmatically?

Import validateDocs and other helpers from the provided script and call validateDocs('.', { quiet: false }) to get a result object with passed, issues, and warnings.