Maintain Docs

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