titan-iac/knowledge/runbooks/kb-authoring.md

title	tags	owners	entrypoints	source_paths
KB authoring: what to write (and what not to)	atlas kb runbooks	brad		knowledge/runbooks scripts/knowledge_render_atlas.py

KB authoring: what to write (and what not to)

The goal

Give Atlas assistants enough grounded, Atlas-specific context to answer “how do I…?” questions without guessing.

What to capture (high value)

• User workflows: “click here, set X, expected result”
• Operator workflows: “edit these files, reconcile this kustomization, verify with these commands”
• Wiring: “this host routes to this service; this service depends on Postgres/Vault/etc”
• Failure modes: exact error messages + the 2–5 checks that usually resolve them
• Permissions: Keycloak groups/roles and what they unlock

What to avoid (low value / fluff)

• Generic Kubernetes explanations (link to upstream docs instead)
• Copy-pasting large manifests (prefer file paths + small snippets)
• Anything that will drift quickly (render it from GitOps instead)
• Any secret values (reference Secret/Vault locations by name only)

Document pattern (recommended)

Each runbook should answer:

• “What is this?”
• “What do users do?”
• “What do operators change (where in Git)?”
• “How do we verify it works?”
• “What breaks and how to debug it?”