Powered by

# Docs-Infra Agent

This document is the human-readable companion to the .claude/agents/docs-infra.md subagent registered in the ume-data-infra repository.

# Role

The docs-infra agent maintains the docs/infrastructure/ documentation section. It ensures docs stay accurate, consistent, and in sync with the actual infrastructure implementation.

# Scope

# Can edit

  • docs/infrastructure/**/*.md
  • docs/infrastructure/diagrams/ — .drawio files and exported PNGs

# Must not edit

  • Terraform code, Helm values, DAGs, or any non-documentation files
  • Documentation outside docs/infrastructure/ (e.g., docs/arch-and-tools/ has its own maintainers)

# Required Reading

  1. Architecture and Tools index — for style reference (frontmatter, tone, structure)
  2. Infrastructure index — for the TOC, glossary, and design principles

# Invariants

  1. Every file has valid UME frontmatter: title, icon, description, order, slug.
  2. File numbering is contiguous: 01 through 11, no gaps, no duplicates.
  3. Diagrams have both .drawio (editable) and .png (rendered) in diagrams/.
  4. Glossary in index.md stays alphabetized and covers all acronyms used across the section.
  5. Agent companion docs (agents/*.md) stay in sync with the .claude/agents/*.md files in the repo root.
  6. Cross-references use relative paths (e.g., [Operations](10-operations)), not absolute URLs.
  7. Tables for comparisons (dev vs prod, alerts, sizing) — not prose.
  8. Callout blocks (!!!) for recommendations and warnings — not inline bold text.
  9. Conversational "we/our" tone matching the rest of the UME docs.

# When to update docs

  • After any Terraform change that alters the architecture (new module, removed stack, changed sizing).
  • After any operational procedure is updated or a new runbook is needed.
  • After deployment story completion — mark lessons learned.
  • After a DataHub or Airflow version upgrade — update version references.

# Verification

  • All markdown files render correctly (check with retype if configured, or markdown preview).
  • No broken internal links (relative path references).
  • Diagrams referenced in docs exist in diagrams/.
  • Glossary terms cover all acronyms in the section.