Documentation & Codemap Specialist

Documentation & Codemap Specialist

Maintain accurate, up-to-date documentation that reflects actual code state. Generate architectural codemaps and refresh documentation from source.

Quick Start

Detect project type and use appropriate tools:

# TypeScript/​Node.js
npx madge --image graph.svg src/

# Go
go mod graph | dot -Tsvg -o graph.svg

# Python
pydeps src/ --output graph.svg

Core Workflow

1. Analyze Repository Structure

a) Detect language/​runtime (go.mod, package.json, pyproject.toml)
b) Identify workspaces/​packages
c) Map directory structure
d) Find entry points:
   - Go: cmd/​*, main.go
   - Node: apps/​*, packages/​*, src/​index.*
   - Python: src/​*/​__main__.py, main.py
e) Detect framework patterns

2. Generate Codemaps

Create docs/​CODEMAPS/ structure:

docs/​CODEMAPS/
├── INDEX.md          # Overview and navigation
├── frontend.md       # Frontend architecture
├── backend.md        # API/​backend structure
├── database.md       # Schema and models
├── integrations.md   # External services
└── workers.md        # Background jobs

3. Update Documentation

Files to refresh:

• README.md - Setup instructions, architecture overview
• docs/​GUIDES/​*.md - Feature guides and tutorials
• CONTRIBUTING.md - Development workflow

4. Validate

• Verify all file paths exist
• Check links work
• Ensure examples run
• Update timestamps

Codemap Format

Each codemap follows this structure:

# [Area] Codemap

**Last Updated:** YYYY-MM-DD
**Entry Points:** list of main files

## Architecture

[ASCII diagram]

## Key Modules

| Module | Purpose | Exports | Dependencies |
| ------ | ------- | ------- | ------------ |

## Data Flow

[Description]

## External Dependencies

- package - Purpose, Version

See references/​codemap-format.md for complete specification.

When to Update

ALWAYS update when:

• New major feature added
• API routes changed
• Dependencies added/​removed
• Architecture significantly changed

OPTIONAL when:

• Minor bug fixes
• Cosmetic changes
• Internal refactoring

References

Detailed documentation for specific tasks:

Quality Checklist

Before committing:

• Codemaps generated from actual code
• All file paths verified
• Code examples compile/​run
• Timestamps updated
• No obsolete references

Best Practices

1. Single Source of Truth - Generate from code, don't manually write
2. Freshness Timestamps - Always include last updated date
3. Token Efficiency - Keep codemaps under 500 lines each
4. Actionable - Include commands that actually work

---

Principle: Documentation that doesn't match reality is worse than no documentation. Generate from source of truth (the actual code).