Menu
Audit and update documentation after code changes. Use when architecture, APIs, or behavior changed and docs may have drifted.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
| 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.json orbit-query; keep shell commands in separate shell fences.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.
Index and query a LOCAL checkout of a repository offline with the Orbit local CLI (the `orbit` binary, run directly or via `glab orbit local`). It builds a DuckDB property graph from the working tree and you query it with read-only SQL. Use when the request targets the current checkout, working tree, or a branch that is not pushed/indexed remotely, or is explicitly offline/local: index this repo locally, who calls X in my checkout, list definitions in a file, generate a repo map of a local checkout, run SQL over the local code graph, or serve the local graph over MCP. For queries against already-indexed production data in GitLab (a project such as gitlab-org/gitlab, cross-project blast radius, contributor or merge-request aggregation) use the `orbit` skill; for single-entity GitLab lookups or write operations use `glab`.
AST-based code search and rewrite via tree-sitter patterns. Use instead of Grep/Edit when a change spans many sites or must respect code structure: structural matching, multi-file batch rewrites, or context-aware queries (e.g. "unwrap inside impl blocks"). Not for a single-file or single-symbol rename — use Edit for that.
Registry of related repositories (Siphon, Rails, and other consumed repos) with their git URLs and local checkout paths. Use when you need to find where a related repo is checked out locally, get its git URL, or clone it if it is missing.
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 that require relationship traversal or aggregation, repository map / repo-map generation, and any question spanning relationships, cross-entity joins, or multi-entity aggregation across GitLab entities (projects, users, MRs, issues, pipelines, files, definitions, vulnerabilities). Do not use for single-entity GitLab lookups or write operations that `glab` handles directly (e.g. `glab mr view`, `glab mr create`).
Remove and tighten unnecessary LLM-generated comments — including narration disguised as "why", restated constraints, and why-comments a named symbol or the code structure already conveys. Use while editing, and as the final narration-comment pass before opening an MR or pushing, to strip the LLM narration the model left behind.
Investigate query evaluation failures in the Knowledge Graph synthetic data pipeline. Use when queries fail or return unexpected results after running the evaluate binary.