Bring a project's documentation in line with the code changes on the current branch, so doc updates land in the same PR as the code and get reviewed together. Project-agnostic: discover the project's doc conventions first, then apply this workflow.
-
Locate the docs and learn the conventions. Don't assume a layout — find it:
git ls-files | grep -iE '(^|/)(docs?|documentation|content)/' | head -50
Common homes: a docs/ dir, a packages/docs or website/ package (Astro/Starlight, Docusaurus, VitePress, mkdocs), a top-level README.md, or man/. Identify which generator (if any) by checking for astro.config.*, docusaurus.config.*, mkdocs.yml, *.vitepress, etc.
- Read any docs-specific guidance first — a
CLAUDE.md/AGENTS.md/README.md inside the docs dir, or a ## Docs section in the repo's root CLAUDE.md. Follow its house style and gotchas.
- Note which files are generated (build artifacts like
dist/, llms.txt, per-page .md exports, API reference dumps). Never hand-edit generated output — edit the source it's built from.
-
Get the diff. Determine the base branch (usually main or master; check git remote show origin or the repo's default) and diff against it:
git diff <base>...HEAD --stat
git diff <base>...HEAD
If on the base branch or there's no diff, stop and tell the user there's nothing to sync.
-
Decide if docs are even in scope. Doc-relevant changes are user-facing: CLI commands/flags, public API signatures, config options, env vars, UI flows, install/build/setup steps, and behavior changes a user would notice. Pure internal refactors, tests, and CI changes usually need no doc update — say so and stop rather than inventing edits.
-
Map changes to pages. For each user-facing change, find the page(s) that describe it. Grep the docs for the old name/flag/value to catch every mention:
grep -rn "<old-flag-or-name>" <docs-dir>
Renamed/removed things are the highest-value catch — stale references mislead users.
-
Edit the source pages. Make the smallest change that makes the docs correct. Match the existing voice, structure, and any callout/aside syntax the generator uses. If you add or rename a page, update whatever the project uses for navigation (sidebar config, _sidebar, frontmatter slug, nav YAML) and fix in-content links to it.
-
Flag what you can't map. If a code change clearly affects users but you can't confidently place it (or it needs a screenshot, a decision, or content you don't have), don't guess — list it for the user to handle, with the file/change and your best suggestion.
-
Verify the build, if there is one. If the docs are part of a buildable site, run its build to surface broken links/nav (e.g. the docs package's build script). This catches errors dev mode hides. Don't claim done until it passes. If there's no build step, re-read your edits for correctness.
-
Report. Summarize: pages edited (and why), pages checked but left unchanged, and anything flagged for the user. Leave committing/PR creation to the user unless they ask.
