---
name: docouture-documenting-changes
description: "How to update an existing docouture documentation site when a feature, change, deprecation or fix lands in the repo — figuring out what's affected from a diff/commit/PR, confirming with the user before writing, and keeping AGENTS.md's documentation-state ledger honest. USE WHEN a new feature was just added, something was deprecated or removed, a fix changes documented behaviour, or docs feel out of date relative to the code. EXAMPLES: 'I added a new CLI flag, update the docs', 'this API is now deprecated, reflect that in the docs', 'document this change', 'my docs are stale, what needs updating'."
---

# Documenting changes

This is the re-entry point for a docouture site that already exists (scaffolded and
drafted via `docouture-getting-started`) and needs to stay in sync as the repo evolves. Use
this every time something changes, not just once — it's the loop, not a one-shot pass.

If there's no site yet at all, this is the wrong skill — see `docouture-getting-started`
first.

## Non-negotiable trigger check

Before considering ANY code change in this repo done — not just when the user explicitly
asks to "update the docs" — check whether it needs this skill:

1. List the file(s) you just touched.
2. Grep the root `AGENTS.md`'s "Documentation state" table for each one, against every
   row's `derived from` column (globs like `antora-extensions/lib/*.js` count — check the
   directory, not just the exact filename).
3. Any hit means that row's doc page now describes stale behaviour and this skill applies
   to this change, right now, as part of the same piece of work — not a follow-up, not
   something to wait to be asked for a second time.
4. No hit doesn't necessarily mean "skip it" either — the table is hand-maintained and can
   itself be stale (see `reference/maintenance-loop.md`); a change to something clearly
   user-facing (a new CLI flag, a config key, a changed extension behaviour) still warrants
   a quick check of whether a doc page describes the old behaviour even if nothing in the
   table points at the file you touched.

This skill decides *what* changed and *whether* it needs a docs update; once it knows
which page(s) to touch, it hands off to the same skills `docouture-getting-started` does:

- **`docouture-docs-internals`** — module/page/nav mechanics.
- **`docouture-writing-docs-pages`** — AsciiDoc authoring itself.
- **`docouture-authoring-guides`** — the touched page's content contract: what that section
  says, in what order, and its quality bar — so an edit to an existing `reference` or
  `guides` page still matches its section's pattern rather than drifting from it.

See `reference/maintenance-loop.md` for the full mechanism: the `AGENTS.md`
documentation-state ledger, what counts as drift, and when to revisit the home page.

## The flow, in short

1. **Find out what changed.** Prefer inspecting the actual change first — a git diff, the
   commit(s) since the last documented pass, or a PR's description — over asking the user
   to enumerate it themselves. This is a starting point to *propose from*, not something to
   trust blindly: confirm your read of "what changed" with the user before writing
   anything, since inferred intent can be wrong (a refactor that touches many files is not
   the same as a new feature, even though both produce a large diff).
2. **Re-scan the repo's surface** the same way `docouture-getting-started`'s
   `content-sourcing.md` step 3 describes — exports, CLI commands, config keys, API
   definitions — and diff it against `AGENTS.md`'s ledger. See `reference/maintenance-loop.md`
   for exactly what counts as `new`, `stale` and `current`.
3. **Check whether this needs a new page, an edit to an existing one, or a structural
   change** (a whole new module, if this is a monorepo gaining a new publishable artifact —
   see `docouture-getting-started`'s `reference/structure-planning.md` for that decision; this
   skill doesn't re-litigate structure on its own, it flags when structure planning is
   needed and hands back to that skill for the decision).
4. **Write the update**, following whatever page pattern already fits
   (`docouture-docs-internals`'s `reference/page-patterns.md`), the content contract for
   that page's section (`docouture-authoring-guides`), and the site's existing voice —
   a code-derived reference page reads differently from a hand-written guide, don't force
   one to imitate the other.
5. **Update the ledger** in `AGENTS.md` — mark the touched page(s) `current` again, add a
   row for anything genuinely new, and never silently regenerate a page marked `manual`
   (human-owned) without being asked.
6. **Check `nav.adoc`** for the module(s) touched — a page that exists on disk but isn't
   listed there builds fine and is simply unreachable; nothing warns about this on its own.

## What this skill deliberately doesn't do automatically

It never regenerates a whole site's structure from scratch on every change (that's
`docouture-getting-started`'s job, and only ever needed once, or for a genuine restructure),
and it never writes past what a diff/commit actually supports without checking with the
user first — a hybrid of "look at the change" and "confirm before touching docs," not pure
guesswork and not pure Q&A.