| name | update-docs |
| description | Update repo documentation (flow, app map, architecture, README, module docs) so it matches current code. Use when docs are stale and need to be reconciled with the codebase. |
Update Docs
Edit repo docs that explain how code works (flow docs, app/module maps, architecture overviews, README, module-local markdown). Surgical edits, not rewrites.
1. Identify target
Infer or ask for the target doc. Prefer existing docs over new ones:
- Subsystem flow → nearby flow doc.
- App-wide navigation/module map → app map doc.
- System-level structure → architecture doc.
- Setup/usage →
README.md.
If the doc does not exist, ask via AskUserQuestion before creating. Never invent a new doc location silently.
2. Read first
Read the target fully via Read before editing. Also read nearby related docs (neighbouring flow docs, app/architecture docs, README, module-local docs). Match the existing style, structure, vocabulary, and detail level.
3. Verify against code
Inspect the code the doc describes. Update from code reality, not guesses. Check entrypoints, main functions/classes, data flow, state changes, side effects, deps, error/fallback paths, files involved.
Unverifiable claims → remove or move to an Open questions section. Never present guesses as facts.
4. Surgical edits
Default to small edits via Edit: keep useful sections, update stale ones, add missing flows, remove false claims, preserve heading style and tone. Rewrite the whole file via Write only if it is too stale to salvage; if so, say why before editing.
5. Freshness block
If it fits the doc's style, add or update at the bottom:
## Freshness
Last checked against code: YYYY-MM-DD
Relevant files checked:
- `path/to/file.py`
- `path/to/other_file.py`
Use today's date. Include only files actually inspected.
6. Sanity check
After editing: re-read via Read, confirm referenced paths exist, every major claim maps to code or a cited doc, no stale contradiction with nearby docs. Summarise the change.
7. Recommend next step
Recommend one: /zoo-explore (still unclear), /zoo-feature (plan emerged), /zoo-refactor (tangled-but-working code), /zoo-fix (bug found), /zoo-commit-and-document (done). Do not auto-run.
Complete
COMPLETION PROTOCOL: Your final text message is your return value. Output this summary, then STOP — do not call any more tools.
- docs updated (file paths)
- what changed (summary)
- status (complete / blocked with reason)
- recommended next command
Context economy
Before broad reads, locate relevant files/symbols with Glob, Grep, or targeted file reads.
Prefer targeted Read with line ranges or block reads once the relevant area is known.
Read full files only when structure, ordering, or surrounding context is required for correctness.
Do not re-read unchanged files; use prior findings unless the file changed.
