docs-update-from-diff ยท diff
git:20260315.a8bc25b to git:20260424.e47b228
36 added, 15 removed. Audit A to A.
---
name: docs-update-from-diff
- description: Review local code changes with git diff and update the official docs under docs/ to match. Use when the user asks to document current uncommitted work, sync docs with local changes, update docs after a feature or refactor, or when phrases like "git diff", "local changes", "update docs", or "official docs" appear.
+ description: Review local code changes with git diff and update the official
+ docs under docs/ to match. Use when the user asks to document current
+ uncommitted work, sync docs with local changes, update docs after a feature or
+ refactor, or when phrases like "git diff", "local changes", "update docs", or
+ "official docs" appear.
---
# Docs Update From Diff
## Overview
- Inspect local diffs, derive the documentation impact, and update only the repository's `docs/` pages. Treat the current code as the source of truth and keep changes scoped, specific, and navigable.
+ Inspect local diffs, derive the documentation impact, and update only the
+ repository's `docs/` pages. Treat the current code as the source of truth and
+ keep changes scoped, specific, and navigable.
- Read [references/docs-surface.md](references/docs-surface.md) before editing if the affected feature does not map cleanly to an existing docs section.
+ Read [references/docs-surface.md](references/docs-surface.md) before editing if
+ the affected feature does not map cleanly to an existing docs section.
## Workflow
### 1. Build the change set
Start from local Git state, not from assumptions.
- - Inspect `git status --short`, `git diff --stat`, and targeted `git diff` output.
- - Focus on non-doc changes first so the documentation delta is grounded in code.
- - Ignore `README.md` and other non-`docs/` content unless they help confirm intent.
+ - Inspect `git status --short`, `git diff --stat`, and targeted `git diff`
+ output.
+ - Focus on non-doc changes first so the documentation delta is grounded in
+ code.
+ - Ignore `README.md` and other non-`docs/` content unless they help confirm
+ intent.
### 2. Derive the docs impact
- For every changed behavior, extract the user-facing or developer-facing facts that documentation must reflect.
+ For every changed behavior, extract the user-facing or developer-facing facts
+ that documentation must reflect.
- New command, flag, config key, default, workflow, or limitation
- Renamed behavior or removed behavior
- Changed examples, paths, or setup steps
- New feature that belongs in an existing page but is not mentioned yet
- Prefer updating an existing page over creating a new page. Create a new page only when the feature introduces a stable topic that would make an existing page harder to follow.
+ Prefer updating an existing page over creating a new page. Create a new page
+ only when the feature introduces a stable topic that would make an existing page
+ harder to follow.
### 3. Find the right docs location
Map each change to the smallest correct documentation surface:
- End-user behavior: `docs/users/**`
- - Developer internals, SDKs, contributor workflow, tooling: `docs/developers/**`
+ - Developer internals, SDKs, contributor workflow, tooling:
+ `docs/developers/**`
- Shared landing or navigation changes: root `docs/**` and `_meta.ts`
- If you add a new page, update the nearest `_meta.ts` in the same docs section so the page is discoverable.
+ If you add a new page, update the nearest `_meta.ts` in the same docs section so
+ the page is discoverable.
### 4. Write the update
Edit documentation with the following bar:
- State the current behavior, not the implementation history
- Use concrete commands, file paths, setting keys, and defaults from the diff
- Remove or rewrite stale text instead of stacking caveats on top of it
- Keep examples aligned with the current CLI and repository layout
- Preserve the repository's existing docs tone and heading structure
### 5. Cross-check before finishing
Verify that the updated docs cover the actual delta:
- Search `docs/` for old names, removed flags, or outdated examples
- Confirm links and relative paths still make sense
- Confirm any new page is included in the relevant `_meta.ts`
- Re-read the changed docs against the code diff, not against memory
## Practical heuristics
- - If a change affects commands, also check quickstart, workflows, and feature pages for drift.
- - If a change affects configuration, also check `docs/users/configuration/settings.md`, feature pages, and auth/provider docs.
- - If a change affects tools or agent behavior, check both `docs/users/features/**` and `docs/developers/tools/**` when relevant.
- - If tests reveal expected behavior more clearly than implementation code, use tests to confirm wording.
+ - If a change affects commands, also check quickstart, workflows, and feature
+ pages for drift.
+ - If a change affects configuration, also check
+ `docs/users/configuration/settings.md`, feature pages, and auth/provider docs.
+ - If a change affects tools or agent behavior, check both
+ `docs/users/features/**` and `docs/developers/tools/**` when relevant.
+ - If tests reveal expected behavior more clearly than implementation code, use
+ tests to confirm wording.
## Deliverable
- Produce the docs edits under `docs/` that make the current local changes understandable to a reader who has not seen the diff. Keep the final summary short and identify which pages were updated.
+ Produce the docs edits under `docs/` that make the current local changes
+ understandable to a reader who has not seen the diff. Keep the final summary
+ short and identify which pages were updated.