RFC-37 Documentation Generation

Generate RFC-37 compliant documentation for services in this repository.

When to use this skill

• Generating documentation for new services
• Updating documentation after code changes
• Setting up documentation structure for a repository
• Creating feature and concept documentation
• Integrating with RAG systems
• When asked to "generate documentation" or "create docs"

Skill Contents

Sections

• When to use this skill (L24-L32)
• Quick Start (L54-L90)
• Documentation Structure (L91-L128)
• Change Detection (L129-L152)
• References (L153-L161)
• Related Skills (L162-L169)

Available Resources

📚 references/ - Detailed documentation

• atlas mcp usage
• documentation workflow
• templates
• troubleshooting

---

Quick Start

1. Identify Services

Scan

bitso-services/

directory for deployable services:

ls -d bitso-services/*/

Each subdirectory is a separate service to document.

2. Create Documentation Structure

docs/
├── README.md                    # Repository overview
└── <service-name>/              # One folder per service
    ├── overview.md              # Business purpose
    ├── architecture.md          # Dependencies, data flow
    ├── concepts/                # Domain concepts
    │   └── <concept>.md
    └── features/                # Feature documentation
        └── <feature>.md

3. Use Templates

Apply RFC-37 templates from

references/templates.md

or refer to the comprehensive doc-validation-rfc-37 skill for:

• Directory structure requirements
• Confluence metadata configuration
• Documentation linting and validation

4. Run with Idempotency

Only update documentation when code changes. Check existing docs first.

Documentation Structure

Service-Specific Focus

Document only service-specific information:

✅ Document:

• Business purpose and domain concepts
• Service architecture and dependencies
• Features and use cases
• gRPC APIs and contracts
• Data models (PostgreSQL, Redis)

❌ Don't Document (covered in platform docs):

• General local development setup
• Testing patterns
• Monitoring and logging
• Standard architecture patterns
• Deployment processes

Folder Structure

docs/
├── api/                         # Human-managed
├── decisions/                   # Human-managed
├── runbooks/                    # Human-managed
└── <service-name>/              # AI-managed
    ├── overview.md
    ├── architecture.md
    ├── concepts/
    │   ├── <concept-1>.md
    │   └── <concept-2>.md
    └── features/
        ├── <feature-1>.md
        └── <feature-2>.md

Change Detection

Idempotency Rules

1. Only update when code changes
2. Preserve existing content if accurate
3. Don't rewrite just to rephrase
4. Don't change formatting if content is accurate

What Constitutes a Change

UPDATE documentation when:

• New features or concepts added
• Architecture changes
• API contracts change
• Database schema changes
• Business rules change

DON'T update when:

• Code formatting changes
• Variable names change but behavior is same
• Tests modified but functionality unchanged
• Internal refactoring without API changes

References

Reference	Description
references/atlas-mcp-usage.md	MCP queries for Atlas
references/documentation-workflow.md	Full generation workflow
references/templates.md	RFC-37 document templates
references/troubleshooting.md	Common issues and solutions

Related Skills

Skill	Purpose
doc-validation-rfc-37	RFC-37 structure validation, linting, Confluence config
quality-checks	Quality gate orchestration

Note: For RFC-37 compliance validation and Confluence mirroring setup, use the

doc-validation-rfc-37

skill. This skill focuses on AI-assisted content generation.

<!-- AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY --> <!-- Source: bitsoex/ai-code-instructions → global/skills/doc-generation-rfc-37/SKILL.md --> <!-- To modify, edit the source file and run the distribution workflow -->