Skip to main content

The Documentation Commit Pattern

In one line: Every architecture-changing branch ships its artifacts together — code, ADR (if applicable), doc page update, STATE.md + memory updates, build verification — enforced at review.

Every feature branch that changes architecture includes these artifacts:

  1. Code changes — the implementation itself
  2. ADR (if applicable) — if a significant decision was made during implementation
  3. Docusaurus page update — the relevant documentation page reflecting the new state
  4. STATE.md + memory update — regenerate STATE.md and update the relevant memory files in the same commit (Section 6, Appendix J). A branch that moves the project's state without updating STATE.md/memory is incomplete for the same reason code without tests is incomplete.
  5. Build verification — npm run build in the Docusaurus directory confirms the documentation compiles without errors

This pattern is enforced during the review stage (Section 3.3). When a reviewer checks a feature branch, one of the review criteria is: "Does this branch update the relevant documentation?" Code changes without corresponding documentation updates are treated as incomplete — the same way code without tests is treated as incomplete.

The pattern is not burdensome in practice because the documentation update is usually small. Adding a new API endpoint requires adding a row to the API reference table. Adding a new service module requires updating the service inventory. Adding a new ADR requires creating a single file from the template. The effort is proportional to the change, and the payoff — accurate documentation that does not require a separate "catch up" effort — is immediate.

When documentation updates are genuinely unnecessary (bug fixes, configuration changes, internal refactoring that does not change external behavior), the reviewer confirms that no documentation update is needed rather than requiring a pro-forma change.

The doc-pointers manifest (scoped-blocking input, §7.5). A project opts into the blocking code↔doc gate by adding docs/doc-pointers.yaml: a list of { code: <glob>, doc: <path> } mappings. When a mapped code path changes in a commit without its mapped doc, the gate blocks (clear with [skip-docs: <reason>], logged for the §2.8 census). An absent manifest leaves the gate inert — opt-in by construction. The §2.8 census reports the manifest's coverage (mapped globs vs. the changed-code surface) so silent decay — the gate quietly losing reach as the manifest goes stale — is visible rather than invisible. The manifest is the scoped alternative to a blanket age-gate: it blocks only where a human declared a code→doc dependency, not on calendar age.