| name | update-docs |
| description | Update living documentation to match current codebase state. Three modes: `/update-docs` — incremental, all groups, checks CHANGELOG + git log since last run; `/update-docs <group>` — incremental but scoped to one group; `/update-docs full <group>` — deep-reads actual code and compares with docs in a group. Groups: architecture, contracts, agents, ops, workflow. Use when user says "update docs", "docs are stale", "sync documentation", or after a batch of changes lands. Also useful from /checkpoint.
|
| allowed-tools | Bash, Read, Write, Edit, Grep, Glob, Agent |
| argument-hint | [full] <group> |
Update Documentation
Keep living docs in sync with the codebase.
Key References
- See Documentation Map in CLAUDE.md for the full list of docs grouped by purpose.
Modes
/update-docs — incremental, all groups
Cheap and fast. Reads CHANGELOG + git log since last run, figures out what changed, updates only affected docs regardless of which group they belong to.
/update-docs <group> — incremental, scoped
Same as above but only reviews docs from the specified group. Useful when you know you changed something in a specific area and want a quick targeted check.
/update-docs full <group> — deep review
Reads actual source code and compares with every doc in the group. Expensive but thorough — use after major refactors or when a group hasn't been fully reviewed in a while.
A group name is required for full mode — there is no "full everything" option. Reading all docs + all their source code in one pass blows up the context. Run groups separately if you need a complete refresh.
Valid groups: architecture, contracts, agents, ops, workflow.
State
Last-run metadata lives in .claude/skills/update-docs/state.json:
{
"last_run": "2026-03-10",
"last_run_mode": "incremental",
"last_commit": "f3fc97e",
"groups_full_run": {
"architecture": "2026-03-08",
"contracts": "2026-03-10"
}
}
groups_full_run tracks when each group last had a full review — useful for deciding which group needs attention next.
If state.json doesn't exist — this is the first run. For incremental modes, use the last 2 weeks of git history as baseline. In the summary, note that no group has ever had a full review and suggest starting with the most critical one.
Doc Groups
Each group bundles logically related docs. The "Code signals" column tells incremental mode which file changes should flag a doc for review.
architecture — System design & topology
| Doc | Code signals |
|---|
README.md | new/removed services, major architecture shifts |
ARCHITECTURE.md | docker-compose.yml, services/*/, queue constants, Caddy config |
docs/PIPELINE_V2.md | consumer flow, queue topology, node transitions |
docs/parallel-workers.md | worker-manager, docker networking, dual-network setup |
contracts — Schemas, terminology & error handling
| Doc | Code signals |
|---|
docs/CONTRACTS.md | shared/contracts/, shared/models/, API router schemas |
docs/GLOSSARY.md | new concepts in CHANGELOG, renamed entities |
docs/ERROR_HANDLING.md | retry logic, error classes, timeout config |
agents — LangGraph nodes & coding agents
| Doc | Code signals |
|---|
docs/NODES.md | agent prompts, tools, node definitions, subgraph changes |
docs/coding-agents.md | worker-wrapper, worker-manager, agent config |
docs/resource-management.md | secret handles, worker env, allocation logic |
services/langgraph/src/prompts/developer_worker/INSTRUCTIONS.md | CLI tools, worker-wrapper, task lifecycle |
ops — Deploy, secrets, testing, logging, shared recipes
| Doc | Code signals |
|---|
docs/DEPLOY.md | deploy worker, GitHub Actions, Caddy config, infra-service |
docs/SECRETS.md | encryption code, secret-related env vars, GitHub secrets flow |
docs/TESTING.md | Makefile test targets, CI config, pytest setup, new test dirs |
docs/LOGGING.md | shared/log_config.py, structlog usage patterns |
.claude/skills/shared/pipeline-recipes.md | queue APIs, worker-manager API, GitHubAppClient, story/task transitions, debug endpoints |
workflow — Dev process & user stories
| Doc | Code signals |
|---|
docs/DEV_PIPELINE.md | skills, API routes for tasks/stories, scheduler, consumer changes |
Not managed by this skill
docs/CHANGELOG.md — updated by /implement, not by doc syncdocs/backlog.md, docs/STATUS.md, docs/ROADMAP.md, docs/audit.md — managed by sprint skillsdocs/sprints/* — managed by sprint skills (/plan-phase, /implement, /close-phase, /close-sprint)docs/e2e_results/*, docs/brainstorms/* — historical recordsdocs/skill-feedback.md — append-only log.claude/skills/*/SKILL.md — managed by /skill-creatorCLAUDE.md, AGENTS.md — meta-config, edited manually
Protocol
0. Load state
Read state.json. If missing, tell the user this is the first run and ask which group to start with (or suggest one based on recent CHANGELOG activity).
1. Determine scope
/update-docs (incremental, all groups):
git log --oneline --since="<last_run>" --name-only
Also read docs/CHANGELOG.md entries since last_run date — the CHANGELOG describes changes in terms of features and components, which is more useful than raw file paths for understanding what docs need updating.
From changed files + CHANGELOG entries, use the "Code signals" column to determine which docs are potentially affected. Only review those docs, regardless of which group they belong to.
If nothing changed — say so and exit.
/update-docs <group> (incremental, scoped):
Same git log + CHANGELOG analysis, but only consider docs from the specified group. Ignore matches in other groups.
/update-docs full <group> (deep review):
All docs in the specified group are in scope. Read the actual code areas listed in "Code signals" for each doc — not just what changed recently, but the full current state.
2. Review & update each doc
For each doc in scope:
- Read the current doc
- Read the relevant code — use "Code signals" to know where to look. In incremental mode, focus on the specific files that changed. In full mode, do a broader read of the code area.
- Compare — look for: outdated descriptions, missing new features, removed components still mentioned, wrong file paths, stale examples, incorrect command syntax
- Update the doc — edit directly. Keep existing style and structure. Don't rewrite accurate sections.
Guidelines:
- Preserve the author's voice and formatting conventions
- Don't bloat docs with implementation details — keep the same level of abstraction
- If a section is completely wrong, rewrite it; if mostly right, patch it
- When unsure if something changed, check the code rather than guessing
- Update dates/versions where docs show them
- For
ARCHITECTURE.md: update the ASCII diagram if service topology changed
3. Save state
{
"last_run": "<today>",
"last_run_mode": "<mode>",
"last_commit": "<current HEAD sha>",
"groups_full_run": { "<group>": "<today>", ... }
}
For incremental runs, update last_run and last_commit but don't touch groups_full_run.
For full runs, also update the specific group's date in groups_full_run.
4. Commit
git add <updated docs> .claude/skills/update-docs/state.json
git commit -m "docs: update living docs (<mode> sync, <N> files)"
Do NOT push — doc-only commits stay local to avoid wasting CI minutes.
5. Report
## Docs Update Summary
- Mode: incremental [<group>] | full <group>
- Docs reviewed: N
- Docs updated: N (list them)
- Docs unchanged: N
- Notable changes: <brief bullets>
- Groups never fully reviewed: <list>
- Stale groups (last full run >2 weeks ago): <list>
Always check groups_full_run and surface groups that have never been fully reviewed or haven't been reviewed in >2 weeks.
Tips for Incremental Mode
The CHANGELOG is your best friend — it describes changes in terms of features and components, not just file paths. "Worker-manager mounts workspace by repo_id" tells you to check docs/parallel-workers.md and docs/coding-agents.md even if those doc files aren't in the git diff.
Quick heuristics:
shared/contracts/ changes → check docs/CONTRACTS.mddocker-compose.yml changes → check ARCHITECTURE.md- Makefile changes → check
docs/TESTING.md and README.md
- New service directory → check
ARCHITECTURE.md and README.md
- Queue constant changes → check
docs/CONTRACTS.md and docs/PIPELINE_V2.md
Self-Feedback
If you encountered any of these during the run, add an entry to docs/skill-feedback.md:
- A doc should be added to or removed from a group
- The "Code signals" mapping missed something (change X should have flagged doc Y)
- A doc's structure made it hard to update
- A group split doesn't feel right (doc X belongs with group Y instead)
## [update-docs] — <today's date>
- **Type**: registry-gap | signal-mismatch | structure | grouping
- **Problem**: <what went wrong>
- **Suggested fix**: <concrete change>
