doc-maintenance

1# Doc Maintenance
2 
3Keep the documentation honest with minimum churn. The goal is alignment between docs and behavior, not stylistic rewrites or cosmetic re-organization. Reviewers should be able to read a diff and see "this updates docs to match recent behavior changes".
4 
5## When to use
6 
7- A PR or recent set of merges changed user-visible behavior: CLI flags, API shapes, default values, configuration keys, endpoints, environment variables, supported versions.
8- A user-reported bug traced back to outdated documentation.
9- A release is being cut and the docs need a pass against the merged commits.
10- A new feature shipped but only the engineer's PR description describes how to use it.
11 
12## When not to use
13 
14- The change is internal-only (private helper rename, refactor) with no user-visible impact.
15- You want to "improve the docs" without a behavior anchor. That is a separate scoped project, not maintenance — make a plan first.
16 
17## The pass
18 
191. **Establish the baseline.** Get the commit range you are documenting against (since last release tag, since last merged-doc commit, or since a specific PR).
202. **Enumerate user-visible changes.** Read commits and PR descriptions. List, for each change, what a user can now do differently.
213. **Map changes to docs.** For each change, find every page that mentions the affected concept. Common targets: README, CLI reference, API reference, configuration reference, migration guide, FAQ, examples.
22…