Update docs
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.
Where to look
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). |
Gathering context
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.
What drifts most
- New ontology entities missing from
data_model.md
- Query engine changes not in
querying/graph_engine.md
- New CDC topics or handlers missing from
indexing/sdlc_indexing.md
- Security model changes not in
security.md
- Crate renames, splits, or new crates not reflected in
CLAUDE.md
- People or epic changes not in
README.md
- Stale config references in
docs/dev/runbooks/server_configuration.md
- New orbit API endpoints, query types, response-format changes, or user-visible features (e.g. indexing progress added in !1015) not reflected in
skills/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.
Fixing
- Read the stale doc
- Read the code it describes
- Edit the doc to match
- Run
mise run lint:docs to validate
- If you touched CLAUDE.md, mirror the change to AGENTS.md
- If your change alters orbit API behavior (new endpoint, new query type, new response field, new user-visible feature), update
skills/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.
- Fence executable Orbit query JSON as
json orbit-query; keep shell commands in separate shell fences.
Self-improvement
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.
1---2name: update-docs3description: Audit and update documentation after code changes. Use when architecture, APIs, or behavior changed and docs may have drifted.4---56# Update docs78Docs 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.910If agent teams are available, create an agent team for each major section of the documents.1112## Where to look1314`README.md` is the SSOT. Use `/related-repositories` for dependent repos.1516| Location | Contents |17|---|---|18| `README.md` | Epics, repositories, Helm charts, infra, people |19| `docs/design-documents/` | Architecture (indexing, querying, data model, security, observability) |20| `docs/dev/` | Local setup, infrastructure, runbook |21| `CLAUDE.md` / `AGENTS.md` | Agent context. Must stay identical — CI enforces this. |22| `crates/*/README.md` | Per-crate docs |23| `crates/indexer/AGENTS.md` | Indexer agent context |24| `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). |2526## Gathering context2728Before editing, research what changed and what the current state looks like:2930```shell31git log --oneline --since="2 weeks ago" -- crates/query-engine/compiler/32glab issue list --label "knowledge graph" --state opened33glab mr list --state merged --per-page 2034```3536Use `glab` to check epics, issues, and MRs for context on what shipped recently. Cross-reference against what the docs say.3738## What drifts most3940- New ontology entities missing from `data_model.md`41- Query engine changes not in `querying/graph_engine.md`42- New CDC topics or handlers missing from `indexing/sdlc_indexing.md`43- Security model changes not in `security.md`44- Crate renames, splits, or new crates not reflected in `CLAUDE.md`45- People or epic changes not in `README.md`46- Stale config references in `docs/dev/runbooks/server_configuration.md`47- New orbit API endpoints, query types, response-format changes, or user-visible features (e.g. indexing progress added in !1015) not reflected in `skills/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.4849## Fixing50511. Read the stale doc522. Read the code it describes533. Edit the doc to match544. Run `mise run lint:docs` to validate555. If you touched CLAUDE.md, mirror the change to AGENTS.md566. If your change alters orbit API behavior (new endpoint, new query type, new response field, new user-visible feature), update `skills/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.577. Fence executable Orbit query JSON as `json orbit-query`; keep shell commands in separate shell fences.5859## Self-improvement6061When 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.
gitlabhq