doc-generation-rfc-37 skill

---
name: doc-generation-rfc-37
description: >
  Generate and update AI-friendly documentation for services following RFC-37
  templates. Produces concepts/, features/, getting-started/ content with
  Mermaid diagrams and C4 architecture. Use when generating or updating
  service documentation.
compatibility: All services following Bitso patterns; enhanced for Java services
metadata:
  version: "1.0.0"
  rfc: "RFC-37"
  category: documentation
  tags:
    - documentation
    - rfc-37
    - generation
    - rag
---

# 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](#when-to-use-this-skill) (L24-L32)
- [Quick Start](#quick-start) (L54-L90)
- [Documentation Structure](#documentation-structure) (L91-L128)
- [Change Detection](#change-detection) (L129-L152)
- [References](#references) (L153-L161)
- [Related Skills](#related-skills) (L162-L169)

### Available Resources

**📚 references/** - Detailed documentation
- [atlas mcp usage](references/atlas-mcp-usage.md)
- [documentation workflow](references/documentation-workflow.md)
- [templates](references/templates.md)
- [troubleshooting](references/troubleshooting.md)

---

## Quick Start

### 1. Identify Services

Scan `bitso-services/` directory for deployable services:

```bash
ls -d bitso-services/*/
```

Each subdirectory is a separate service to document.

### 2. Create Documentation Structure

```plaintext
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](.claude/skills/doc-validation-rfc-37/SKILL.md) 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

```plaintext
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](references/atlas-mcp-usage.md) | MCP queries for Atlas |
| [references/documentation-workflow.md](references/documentation-workflow.md) | Full generation workflow |
| [references/templates.md](references/templates.md) | RFC-37 document templates |
| [references/troubleshooting.md](references/troubleshooting.md) | Common issues and solutions |

## Related Skills

| Skill | Purpose |
|-------|---------|
| [doc-validation-rfc-37](.claude/skills/doc-validation-rfc-37/SKILL.md) | RFC-37 structure validation, linting, Confluence config |
| [quality-checks](.claude/skills/quality-checks/SKILL.md) | 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 -->