Quick Start

Bash
# Analyze project structure first
find . -name "*.go" -type f | head -20
ls -la internal/ cmd/ pkg/

# Check for reference templates
cat references/README.md
cat references/Architecture.md

# Generate documentation plan
echo "Analyzing endpoints, workflows, and components..."

Workflow

• Load reference templates from skill's references/ directory
• Scan project structure - identify internal/, cmd/, pkg/ organization
• Map components - handlers, services, repositories, adapters
• Extract endpoints - find HTTP routes and business flows
• Identify integrations - external APIs, databases, queues
• Detect workflows - business logic orchestration

• Match templates - align found components with reference templates
• List business endpoints - exclude health/metrics/technical endpoints
• Plan workflow docs - one workflow file per business flow
• Verify coverage - ensure all business flows have workflow docs
• Present plan to user for confirmation

• Generate core docs - README, Architecture, API, Database, Stack
• Create workflow docs - individual files for each business flow
• Generate workflow index - _index.md with all workflow links
• Validate Mermaid - ensure GitLab 10.7.0 compatibility
• Save to ./docs/ directory

Examples

Example 1: Standard Go Service Input: Project with internal/handler/, internal/service/, internal/repository/ Output:

docs/
├── README.md
├── Architecture.md  
├── API.md
├── Database.md
├── Stack.md
├── Workflows/
│   ├── _index.md
│   ├── payment-processing.md
│   └── order-creation.md

Example 2: Mermaid Sequence Input: Payment handler calling service and external API Output:

MERMAID
sequenceDiagram
    Client->>Handler: POST payment
    Handler->>Service: Process payment
    Service->>External API: Validate card
    External API->>Service: Response
    Service->>Repository: Save transaction
    Repository->>Service: Saved
    Service->>Handler: Result
    Handler->>Client: Response

Best Practices

• Always load templates from skill's references/ directory first
• Follow template structure exactly - no additional major sections
• Fill only sections confirmed by actual code
• Don't expand beyond template scope

• Document only what exists in code/config files
• Never infer infrastructure versions or deployment details
• Don't generate operational examples without explicit evidence
• Avoid code snippets unless absolutely necessary for understanding

• Write everything in Russian
• Keep technical terms untranslated
• Use concise, structured, technical style
• Avoid long architectural essays

• Create workflow docs for all business endpoints
• Exclude health/metrics/technical endpoints from workflows
• Ensure one-to-one mapping: business flow → workflow document
• Include all workflows in _index.md

Common Pitfalls

• Don't assume PostgreSQL versions from driver packages
• Don't infer Kubernetes from Dockerfile presence
• Don't generate monitoring stack from /metrics endpoint
• Don't create environment topology from config files

• Don't expand template structure with new major sections
• Don't add "best practices" or architectural recommendations
• Don't generate ADRs without explicit presence in project
• Don't create operational procedures not found in code

• Never fabricate Slack channels, email addresses, URLs
• Don't generate realistic but fictional operational examples
• Avoid placeholder values that look real
• Don't infer CI/CD behavior from pipeline file presence

• Minimize code snippets - prefer explanations
• Don't copy large blocks or full files
• Limit to 10-20 lines maximum when necessary
• Use sparingly - only for complex/non-standard behavior