---
name: document-feature
description: Ship docs in the same diff as the code — add a doc for a new feature, update the existing doc when a feature changes. Use whenever you add a feature or adjust one that is already documented.
---

# Document feature (docs travel with the code)

A feature change is not done until its docs match. **Same diff, not a follow-up.**
Undocumented behavior is a bug; stale docs are worse than none.

## New feature → add the right kind of doc

The repo splits docs by kind (`docs/README.md`). Pick one — don't write all three:

- **Reference doc** — `docs/reference/<name>.md`. A stable "how it works + how to extend
  without coupling" page. Default for a feature others will build on or wire into.
  Shape: follow `docs/reference/roles-and-access.md` (H1 title, intro that links the
  governing ADR/WP, task-oriented `##` sections, `## See also` footer of backticked paths).
- **ADR** — `docs/reference/architecture/NNNN-<slug>.md`. Only when you're recording a
  _decision/pattern_ (a tradeoff, a "we chose X over Y"). One format, no drift:
  `# ADR-NNNN — Title`, then `Status: Accepted · Date: YYYY-MM-DD`, then
  Problem / Options / Decision / Consequences.
- **WP** — `docs/project/archive/backlog/WP-NN-<slug>.md`. Tracked work; use the template at the
  bottom of `docs/project/archive/backlog/README.md`.

Then **add the index row**: `docs/README.md` table for a reference doc/ADR,
`docs/project/archive/backlog/README.md` for a WP. A doc with no index row is invisible.

## Adjusted feature → update what already describes it

Before you call the change done: `grep -ril <feature-name> docs/` and update every hit —
the reference doc's "how to extend" and coupling notes, the ADR's Consequences, the WP's
Outcome/Acceptance. If the change makes a doc claim false, fix the claim in this diff.

## Coupling is the interesting part

For any feature others consume, the doc's most valuable section is **how to extend it and
where the coupling lives** — which shared seams it touches (`ADMIN_LINKS`, the
`role.interceptor` ROLE_AWARE list, `Capability`), and any hand-wired pattern a second
consumer would repeat. Name the coupling; recommend the abstraction only when a real
second case lands (don't refactor speculatively).

## Worked examples

- `docs/reference/stamdata.md`, `docs/reference/audit-log.md`,
  `docs/reference/feature-flags.md` — the three admin-feature reference docs.
- `docs/reference/architecture/0004-stamdata-as-code.md` — the decision behind stamdata.

## Verify

```bash
grep -ril <feature-name> docs/     # every place that mentions it is current
grep -q "<new-doc-path>" docs/README.md   # (or backlog/README.md) — index row exists
```