Documentation Maintainer

Maintain clean, accurate, implementation-focused documentation that works seamlessly with the doc-lookup skill. Ensure docs always reflect current state, are structured for targeted retrieval, and include stable anchors.

Core Principles

1. •Present State Focus: Describe what IS implemented, not what WAS changed. Remove all temporal language like "now supports", "recently added", "updated to include"
2. •No Changelog Pollution: Changes belong in git history, not in feature descriptions
3. •Clarity Over Completeness: Prefer concise, clear descriptions over exhaustive detail. Every sentence must add value
4. •Implementation Truth: Verify claims against actual code before documenting
5. •Single Source of Truth: Each piece of information should exist in exactly one canonical location. Use cross-references with anchors instead of duplicating content
6. •Retrieval-Ready Structure: Organize docs with stable anchors and self-contained sections for doc-lookup skill

Update Workflow

1. •Audit: Verify what's actually implemented
2. •Add/verify anchors: Ensure all major sections have stable anchors (see Anchor Guidelines below)
3. •Remove temporal language: "Recently added", "Now supports", "Updated to", "As of version X"
4. •Consolidate: Merge duplicates, remove repetition, use anchor cross-references
5. •Verify: Cross-reference with actual code
6. •Test retrieval: Verify key sections can be found with doc-lookup skill
7. •Maintain structure: Preserve organization unless improvement needed

Helper Scripts {#helper-scripts}

The maintain-docs skill includes helper scripts for anchor management:

# Add anchors to documentation (dry-run first to preview)
python .claude/skills/maintain-docs/scripts/add_doc_anchors.py <path> --dry-run
python .claude/skills/maintain-docs/scripts/add_doc_anchors.py <path> [--recursive]

# Validate router skill references
python .claude/skills/maintain-docs/scripts/validate_doc_anchors.py

# Or use Makefile shortcuts
make docs-add-anchors-dry    # Preview anchor additions
make docs-add-anchors        # Add anchors to features/formats/projects docs
make docs-validate-anchors   # Validate router skill references

See DOCUMENTATION_MANAGEMENT.md for complete guide.

Anchor Guidelines {#anchor-guidelines}

To enable effective doc-lookup, follow these anchor requirements:

When to Add Anchors

Add explicit anchors {#anchor-id} to:

• •All ## (level 2) headings: Primary sections
• •Important ### (level 3) headings: Key subsections (CLI commands, specific features, patterns)
• •Reference sections: That router skills or other docs will link to

Don't anchor:

• •

  (level 4+) headings unless they're frequently referenced

• •Example headings or minor subsections
• •Temporary or subject-to-change sections

Anchor Granularity Policy

Prefer coarser anchors over fine-grained ones to improve maintainability and usability:

Good (Coarser anchors):

• •#cli-commands for a section covering all CLI commands
• •#mcp-tools for a section listing all MCP tools
• •#service-architecture for service patterns overview

Avoid (Too granular):

• •#cli-run-command, #cli-results-command, #cli-metrics-command (separate anchors for each command)
• •#mcp-dipeo-run-tool, #mcp-list-diagrams-tool (separate anchors for each tool)
• •#service-registry-registration, #service-registry-lookup (separate anchors for minor subsections)

Rationale:

• •Easier maintenance: Fewer anchors to manage when content evolves
• •Better doc-lookup: Router skills can reference one anchor instead of many
• •Natural retrieval: doc-lookup returns the whole section with context
• •Less coupling: Documentation structure can change without breaking references

When fine-grained anchors are acceptable:

• •Distinct, complex subsections with >50 lines each
• •Subsections referenced independently across multiple docs
• •Different conceptual topics that happen to be in the same parent section

Anchor Naming Conventions

Follow these patterns for consistency:

Domain-specific prefixes:

• •#cli-*: CLI-related sections (#cli-commands, #cli-flags, #cli-background)
• •#mcp-*: MCP server sections (#mcp-tools, #mcp-registration, #mcp-architecture)
• •#db-* or #database-*: Database sections (#database-schema, #database-queries)
• •#handler-*: Handler implementation (#handler-patterns, #handler-lifecycle)
• •#codegen-*: Code generation (#codegen-typescript, #codegen-ir-builders)

Generic sections:

• •#overview: High-level introduction
• •#core-responsibilities: Main duties/scope
• •#common-patterns: Usage patterns and examples
• •#troubleshooting: Common issues and solutions
• •#escalation: When to hand off to other agents

Format rules:

• •Use kebab-case: #my-section-name
• •Be descriptive but concise: #cli-flags not #flags, #background-execution not #bg
• •Avoid special characters: Only lowercase letters, numbers, and hyphens
• •Keep stable: Don't rename anchors without updating references

Section Organization for doc-lookup

Structure sections to be self-contained and independently retrievable:

Good section (works well with doc-lookup):

## CLI Flags {#cli-flags}

Common flags for all CLI commands:

- `--light`: Use light diagram format (.light.yaml)
- `--debug`: Enable detailed logging to .dipeo/logs/cli.log
- `--timeout N`: Set execution timeout in seconds (default: 120)

Example:
\`\`\`bash
dipeo run my_diagram --light --debug --timeout=60
\`\`\`

See also: [CLI Commands](#cli-commands)

Bad section (hard to retrieve independently):

## CLI

The CLI has various flags that you can use. Some of them are...
[500 lines of mixed commands, flags, examples, troubleshooting]

Cross-Referencing with Anchors

Instead of duplicating content, use anchor links:

## Background Execution {#background-execution}

For flag details, see [CLI Flags](#cli-flags).
For status checking, see [CLI Commands](#cli-commands).

The background execution system allows...

This enables:

• •Single source of truth
• •Smaller, focused sections
• •Easy doc-lookup navigation

Content Standards

Good Documentation (present tense, anchored, self-contained):

## Service Registry {#service-registry}

The EnhancedServiceRegistry provides:
- Type categorization for services
- Audit trails for all registrations
- Production safety checks

Location: `/dipeo/infrastructure/service_registry.py`

See also: [EventBus](#eventbus), [Service Architecture](#service-architecture)

Bad Documentation (temporal language, no anchors):

## Service Registry

The service registry was recently enhanced to add type categorization
and audit trails. We've also improved the production safety features.

Documentation Elements:

• •Present tense: "provides", "supports", "uses" (not "was enhanced", "now includes")
• •Explicit anchors: All major sections have {#anchor-id}
• •File paths: When relevant, include actual file locations
• •Cross-references: Link to related sections with anchors
• •Self-contained: Section can be understood independently

Documentation Types

Architecture Docs (docs/architecture/):

• •Current design, relationships, decisions
• •Add anchors for key concepts: #service-architecture, #graphql-layer, etc.
• •Remove completed migration notes

Agent Guides (docs/agents/):

• •Domain-specific guidance for specialized agents
• •Must have anchors for all major sections (router skills reference these)
• •Self-contained sections for doc-lookup retrieval

Feature Docs (docs/features/):

• •Current functionality and usage instructions
• •Anchor important sections: #mcp-tools, #diagram-export, etc.
• •Remove outdated workflows

API Docs:

• •Current endpoints, parameters, responses
• •Remove deprecated APIs unless explicitly marked

READMEs:

• •Concise setup, usage, and reference
• •Add anchors if README is long (>200 lines)

Quality Checklist

Before finalizing updates:

Content Quality:

• •✓ Describes current implementation?
• •✓ Verifiable in codebase?
• •✓ Temporal language removed?
• •✓ Simplest accurate description?
• •✓ Adds unique value?
• •✓ Not duplicating content from elsewhere?

doc-lookup Compatibility:

• •✓ Major sections (## headings) have explicit anchors?
• •✓ Anchors follow naming conventions (kebab-case, domain prefixes)?
• •✓ Sections are self-contained and independently retrievable?
• •✓ Cross-references use anchors instead of duplicating content?
• •✓ Can key sections be found with doc-lookup skill?

Testing Retrieval: Test that important sections can be retrieved:

python .claude/skills/doc-lookup/scripts/section_search.py \
  --query "your-anchor-name" \
  --paths docs/your-file.md \
  --top 1

Red Flags

Remove:

• •Historical narratives ("First we did X, then Y")
• •Version notes ("In v2.0 we changed...")
• •Redundant examples
• •Overly detailed obvious concepts
• •Apologetic language ("This might...", "Hopefully...")
• •Sections without anchors (for level 2 headings)
• •Duplicate content that could be cross-referenced
• •Monolithic sections that mix multiple topics

Warning Signs (sections that need splitting):

• •Section longer than 100 lines
• •Multiple topics mixed in one section
• •Difficult to describe in a single anchor name
• •Can't be retrieved independently

Anchor Stability & Maintenance

Renaming Anchors

Anchors are referenced by:

• •Router skills (.claude/skills/dipeo-*/SKILL.md)
• •Cross-references in other docs
• •External links

Before renaming an anchor:

1. •Search for all references: grep -r "your-anchor" .claude/skills/ docs/
2. •Update all references first
3. •Then rename the anchor
4. •Test with doc-lookup

Adding New Sections

When adding a new section:

1. •Choose a descriptive anchor following naming conventions
2. •Ensure section is self-contained
3. •Add cross-references to related sections
4. •Consider updating router skills if it's a major addition

Router Skill Sync

After major documentation updates:

1. •Check if router skills need updating (.claude/skills/dipeo-*/SKILL.md)
2. •Verify anchor references are still valid
3. •Add new anchors to router skill indexes if needed

Examples

Example 1: Updating CLI Documentation

Before (no anchors, temporal language):

## CLI

The CLI was recently updated to support background execution.
You can now run diagrams in the background using the --background flag.
We've also added better error handling.

After (anchored, present tense, cross-referenced):

## CLI Commands {#cli-commands}

Core commands:
- `dipeo run`: Execute a diagram
- `dipeo results`: Check execution results
- `dipeo metrics`: Profile execution performance

For flags, see [CLI Flags](#cli-flags).
For background execution, see [Background Execution](#background-execution).

## CLI Flags {#cli-flags}

Common flags for all commands:
- `--light`: Use light diagram format
- `--debug`: Enable detailed logging
- `--timeout N`: Set timeout in seconds

## Background Execution {#background-execution}

Execute diagrams asynchronously:

\`\`\`bash
dipeo run my_diagram --background
# Returns: {"session_id": "exec_...", "status": "started"}
\`\`\`

Check results: `dipeo results <session_id>`

Example 2: Architecture Documentation

Before (monolithic, no anchors):

## Architecture

DiPeO uses a service registry for managing services. It provides
type categorization and audit trails. We also have an EventBus
for communication...
[200 lines of mixed architecture topics]

After (split sections, anchored):

## Service Architecture {#service-architecture}

DiPeO's service layer uses:
- [Service Registry](#service-registry): Type-safe service management
- [EventBus](#eventbus): Unified event protocol
- [Envelope Pattern](#envelope-pattern): Standardized outputs

## Service Registry {#service-registry}

The EnhancedServiceRegistry provides:
- Type categorization (AI, STANDARD, LLM)
- Audit trails for registrations
- Production safety checks

Location: `/dipeo/infrastructure/service_registry.py`

## EventBus {#eventbus}

Unified event protocol for cross-service communication.

Location: `/dipeo/infrastructure/event_bus.py`

Best Practices Summary

1. •Add anchors to all level 2 headings and important level 3 headings
2. •Use domain prefixes (#cli-, #mcp-, #handler-*) for consistency
3. •Keep sections self-contained (20-50 lines ideal)
4. •Cross-reference instead of duplicating content
5. •Test retrieval with doc-lookup skill
6. •Maintain anchor stability (update references before renaming)
7. •Sync router skills after major documentation changes

The goal is documentation that:

• •Serves developers efficiently
• •Accurately reflects the current system
• •Works seamlessly with doc-lookup skill
• •Requires minimal maintenance through stable anchors and single source of truth