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.