# Documentation

> Applies when: writing docs, comments, READMEs; recording decisions.

Document intent/decisions; public inputs, outputs, errors, and gotchas; non-obvious
constraints; and real build/test/run commands. Update with behavior; prefer one runnable
example. Do not restate code or types.

## Drift check (docs describe what runs)

A documented command/example that no longer runs is a **documentation-drift finding** at
review/polish: run it — failure plus output is the evidence. A behavior change updates the
doc or records the divergence; doc and code never hold contradictory "truths".

## Record decisions

- Capture significant context, decision, consequences, accepted trade-off, change trigger,
  and why viable alternatives lost. DevRites uses `decisions.md` for feature decisions.
- ADRs move `PROPOSED → ACCEPTED → SUPERSEDED / DEPRECATED`. Preserve accepted history;
  a replacement ADR cites and supersedes the old one rather than rewriting it.

## Promote durable guidance

Promotion is maintenance of an existing authority, not a new memory system.

1. **Trigger:** the same reviewed correction appears in at least two distinct features, or
   one explicit product/architecture decision has durable rationale. A one-off, generic,
   stale, or merely inferred observation does not trigger promotion.
2. **Ground:** verify each current claim against live authoritative repository sources.
   Report the source and currentness signal. Unverifiable means `unknown`, not false.
3. **Scope:** state when the guidance applies and does not apply. Reject a candidate whose
   observable trigger cannot be named. If final code/tests/docs already recover the
   reasoning, reject or consolidate the lesson; promote only the missing durable constraint.
   **Failing case:** a regression test already explains input rejection, yet a second
   generic "validate input" rule is added with no lost reasoning identified.
4. **Own and expose:** choose one existing canonical owner (`AGENTS.md`/`CLAUDE.md`, a scoped
   standard, or an ADR) and name the phases, agents, or contributors that discover it and
   how (direct read, index link, or existing on-demand route).
5. **Reconcile:** search current guidance for duplicates, contradictions, and supersession.
   Update, narrow, replace, or retire contradicted guidance at its owner; do not append a
   competing rule. Record the conflict/retirement disposition.
6. **Approve:** show evidence and the exact durable edit before writing; user approval is
   required. Never create a learning ledger, index, queue, score, or parallel authority.

Long reference material stays behind its existing on-demand route.

## Living documents

Canonical documents are updated, not appended to. When truth changes, rewrite the
owning section in the present tense; sealed artifacts take dated deltas through the
owning rite instead ([`core.md`](core.md) #4). Pick a steering verb deliberately —
`create`, `consolidate`, `split`, `trim`, `retire` — rather than letting the last-opened
file absorb every new topic. Document what code cannot own (contracts, invariants,
decisions, rationale); a doc that restates implementation drifts the day it lands.
Sparse is correct — never pad a document to look complete.