doc-updater

Documentation & Codemap Specialist

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

Related Skills:

• kavak-documentation - Query for Kavak documentation standards, README templates, architecture docs format
• Use kavak-platform/platform_docs_search MCP tool for Kavak-specific documentation patterns

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/` with one file per major architectural area. The specific files depend on the project — adapt to what exists:

docs/CODEMAPS/ ├── INDEX.md # Overview and navigation (always) ├── .md # One per major area (examples below)

**Common areas**: frontend, backend/api, database/models, integrations/external, workers/jobs, cli, shared/utils. Only create codemaps for areas that actually exist in the project.

### 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:

```markdown
# [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:

Reference	Purpose
references/codemap-format.md	Complete codemap specification
references/codemap-examples.md	Frontend, backend, integrations examples
references/scripts.md	Generation scripts (ts-morph, madge)
references/scripts-go.md	Go-specific tools and scripts
references/maintenance.md	Schedule and quality checklist
references/readme-template.md	README update template

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).