# Documentation with Code Changes (#447) Keep user-facing documentation current when code changes. Full rules live here so they are **not** always-loaded into AGENTS.md (consumer token cost). Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY. **See also** (load only when needed): - [coding.md](coding.md) — general coding standards - [../skills/deft-directive-pre-pr/SKILL.md](../skills/deft-directive-pre-pr/SKILL.md) — pre-PR checklist (operational) - [../docs/good-agents-md.md](../docs/good-agents-md.md) — AGENTS.md structure ## When docs are required - ! If the change alters **user-visible behavior**, update the matching user-facing surface in the **same PR** (or same commit batch before PR) - ! User-facing surfaces include, as applicable: - CHANGELOG.md under `[Unreleased]` (when the change is user- or operator-visible) - CLI help / `commands.md` (or equivalent) when adding or changing a user-invoked command or flag - Getting-started / README pointers when install or first-run behavior changes - Skill or strategy "When to use" / trigger text when workflow entry points change - ~ Prefer updating the **canonical source** (xBRIEF, content pack, policy) and re-rendering generated views — do not hand-edit generated markdown as the sole fix - ⊗ Claim "docs updated" or "documented" without the documentation files appearing in the diff ## When docs are optional - ? Invent documentation for pure internal refactors with no user-visible behavior change - ~ Internal-only comments and maintainer notes MAY ship without user-facing doc updates - ⊗ Expand always-loaded AGENTS.md with long documentation-discipline essays — keep this file lazy-loaded ## Honesty - ! Documentation claims obey fail-loud / outcome verification (coding.md § Fail Loud): no completion claims that hide missing doc surfaces - ~ If a required surface is skipped, say so explicitly and why (same standard as "checks not run") ## Anti-Patterns - ⊗ Shipping a new public task/CLI verb with no help or commands entry - ⊗ Leaving CHANGELOG stale after a user-visible fix - ⊗ Orphan docs (new md not reachable from AGENTS/README/reference chain — see pre-pr #644 / #647)