Update Docs Workflow

Use this workflow whenever code has changed and the project documentation needs to be brought up to date. The agent uses git to detect what changed since the last documentation commit, analyses the diff, and updates only the affected docs.

This workflow is project-agnostic: it auto-detects the project root and documentation location.

Step 1 — Orient: detect the project

// turbo Run the following to establish the project root and basic structure:

# Project root and current branch
git rev-parse --show-toplevel && git branch --show-current

# Last 5 commits (so we can pick the baseline)
git log --oneline -5

Then find where the documentation lives:

# Look for common doc directory patterns
find "$(git rev-parse --show-toplevel)" -maxdepth 3 -type d \
  \( -name "docs" -o -name "doc" -o -name "wiki" -o -name "pages" \) \
  ! -path "*/.git/*" ! -path "*/node_modules/*" ! -path "*/.venv/*"

# Also check for top-level markdown files
find "$(git rev-parse --show-toplevel)" -maxdepth 1 -name "*.md" -type f

From the results, identify:

$ROOT: the git root directory
$DOCS_DIR: where the documentation files are (e.g. docs/src/, docs/, wiki/)

If $DOCS_DIR cannot be determined automatically, ask the user: "Where are your documentation files? (e.g. docs/, docs/src/, or README.md only)"

Step 2 — Find the baseline commit

// turbo Find the most recent commit that touched the documentation directory:

git log --oneline --all -- "$DOCS_DIR" | head -5

Note the first hash — call it <baseline>. This is the last point in time when docs were current.

If no doc commits exist, use the initial commit as baseline:

git log --oneline --all | tail -1

Step 3 — Get the code diff since the baseline

// turbo First, a compact summary of what changed in source code (not docs):

git diff <baseline> HEAD --stat -- . \
  ':!'"$DOCS_DIR" ':!*.md' ':!*.rst' ':!*.txt' ':!*.json'

If the diff is manageable, get the full diff:

git diff <baseline> HEAD -- . \
  ':!'"$DOCS_DIR" ':!*.md' ':!*.rst' ':!*.txt' ':!*.json'

Tip: If the diff exceeds ~400 lines, analyse it file by file using:
git diff <baseline> HEAD -- path/to/file.py
Focus on: new/deleted classes or functions, changed method signatures, new modules, changed configuration keys, new data files.

Step 4 — Discover existing documentation structure

Read the documentation files discovered in Step 1. Understand:

What topics each file covers
What module/component/concept each file documents
The writing style (language, heading level, use of code blocks, tables)

Maintain the same style and language as the existing docs when making edits.

Step 5 — Map changes to affected docs

For each changed file or module, determine which documentation file(s) need updating.

General mapping heuristics (adapt to the specific project structure):

Type of code change	What to update
New class or module added	Add it to whichever architecture/overview doc covers that layer; update dependency diagrams
Class or function deleted	Remove or strike from all docs that mention it
Method signature / parameter changed	Update code examples, parameter tables
New config key or environment variable	Update configuration docs
New external dependency added	Update setup/installation docs
Data schema changed (DB, JSON, Pydantic, etc.)	Update data model docs
New CLI command or flag	Update CLI reference / usage docs
Behaviour change (algorithm, business logic)	Update design/architecture docs
New test coverage (major new tests)	No doc update usually needed unless testing guide exists

Step 6 — Make surgical edits to affected docs

Update only the sections that are out of date. Do not rewrite sections that are still accurate.

Edit rules:

Add new items (classes, methods, parameters, config keys) that appeared in the diff
Remove or revise descriptions of things that were renamed, deleted, or refactored
Update flow diagrams, step-by-step pipelines, and tables to reflect new reality
Preserve all sections not touched by the diff — no gratuitous rewrites
Match the writing style of the existing doc exactly (language, formatting, code fence style)

Step 7 — Summarise changes and optionally commit

After all edits, display a brief summary:

Which doc files were modified
What was added / removed / updated in each

Then ask the user: "文档已更新。是否要将这些改动提交到 Git？(Y/n)"

If yes, suggest a commit message in the format:

docs: update <DOCS_DIR> to reflect changes since <baseline-short-hash>

Then run (replace <DOCS_DIR> and <message> accordingly):

git add <DOCS_DIR> && git commit -m "<message>"

If no, remind the user that all files are already saved and can be committed later with:

git add <DOCS_DIR> && git commit -m "docs: ..."

update-docs