Agent Skills: RFC-37 Documentation Generation

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
• Quick Start
• Documentation Structure
• Change Detection
• References
• Related Skills

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.