// Audit and update documentation after code changes. Use when architecture, APIs, or behavior changed and docs may have drifted.
| name | update-docs |
| description | Audit and update documentation after code changes. Use when architecture, APIs, or behavior changed and docs may have drifted. |
| allowed-tools | Read, Edit, Write, Glob, Grep, Bash(mise *), Bash(npx *), Bash(git *), Bash(glab *) |
Docs rot when code moves faster than prose. After a code change, check if the docs still describe reality. Fix what drifted. Skip what didn't.
If agent teams are available, create an agent team for each major section of the documents.
README.md is the SSOT. Use /related-repositories for dependent repos.
| Location | Contents |
|---|---|
README.md | Epics, repositories, Helm charts, infra, people |
docs/design-documents/ | Architecture (indexing, querying, data model, security, observability) |
docs/dev/ | Local setup, infrastructure, runbook |
CLAUDE.md / AGENTS.md | Agent context. Must stay identical — CI enforces this. |
crates/*/README.md | Per-crate docs |
crates/indexer/AGENTS.md | Indexer agent context |
skills/orbit/ | Agent skill for Knowledge Graph queries. SKILL.md, references/recipes.md, references/troubleshooting.md are hand-written and need updates when API behavior or response shape changes. references/query_language.md is byte-equal-synced from docs/source/queries/ (CI-enforced via orbit-skill-docs-sync, no manual action needed). |
Before editing, research what changed and what the current state looks like:
git log --oneline --since="2 weeks ago" -- crates/query-engine/compiler/
glab issue list --label "knowledge graph" --state opened
glab mr list --state merged --per-page 20
Use glab to check epics, issues, and MRs for context on what shipped recently. Cross-reference against what the docs say.
data_model.mdquerying/graph_engine.mdindexing/sdlc_indexing.mdsecurity.mdCLAUDE.mdREADME.mddocs/dev/runbooks/server_configuration.mdskills/orbit/SKILL.md, references/recipes.md, or references/troubleshooting.md. CI only enforces byte-equal sync of query_language.md — the rest of the skill's hand-written prose (discovery workflow, recipes, gotchas, agent guidelines) won't flag itself as stale.mise run lint:docs to validateskills/orbit/SKILL.md and skills/orbit/references/ (especially recipes.md and troubleshooting.md) to reflect it. CI only catches byte-equal drift of query_language.md; everything else in the skill is manual.When you find drift this skill doesn't cover, add it to "What drifts most" above. If the user provides feedback about missing documentation updates that the agent didn't catch, add it to this skill.
Query the GitLab Knowledge Graph (Orbit) via `glab orbit remote` CLI subcommands or run a local copy with `glab orbit local`. Use for code-structure questions (who calls this function, where is this symbol defined), cross-project dependency and blast-radius analysis, merge-request and contributor queries, and any question answerable by traversing GitLab's unified entity graph (projects, users, MRs, issues, pipelines, files, definitions, vulnerabilities).
Investigate query evaluation failures in the Knowledge Graph synthetic data pipeline. Use when queries fail or return unexpected results after running the evaluate binary.
Profile GKG queries against ClickHouse with the query-profiler CLI. For optimizing query performance, comparing query plans, investigating slow queries, or checking ClickHouse resource usage.
AST-based code search and rewrite via tree-sitter patterns. Use instead of Grep/Edit for structural matching, batch rewrites, or context-aware queries (e.g. "unwrap inside impl blocks").
Investigate the history, usage, and liveness of code using search and git blame/log. Use when determining if code is dead, understanding why something exists, finding all callers before refactoring, or deciding whether something is safe to remove. Also useful for answering "who added this and why" or "is anything still using this".
GitLab Pajamas Design System expert for building UIs with Pajamas components and patterns. Use when: (1) implementing UI that should follow GitLab's Pajamas design system, (2) selecting or configuring Pajamas/GlComponent components (GlButton, GlAlert, GlModal, etc.), (3) translating Figma designs into Pajamas-compliant code, (4) questions about Pajamas component usage, variants, categories, or accessibility, (5) building GitLab-style interfaces, or (6) the user mentions "Pajamas", "GitLab UI", "Gl components", or "design system" in a GitLab context. Works hand-in-hand with the implement-design skill and Figma MCP tools.