Skip to content

Documentation Policy

Purpose

This policy governs documentation for the backend branch in this repository. It applies to all work that changes backend code, schema, runtime behavior, operational procedure, or backend-facing contracts.

1. Source of truth

The source of truth for this backend branch is, in order:

  1. implementation code in app/
  2. effective database state as defined by db/bootstrap.sql plus all applied files in db/migrations/
  3. active backend docs in docs/

Supporting material is not the source of truth unless it is reconciled with the above:

  • intutype_backend_source_of_truth.md
  • openapi.json
  • docs/90_ops/
  • docs/99_archive/
  • generated artifacts and historical delivery notes

If documentation conflicts with code or migrations, update the documentation immediately. Do not preserve known drift.

2. When docs must be updated

Documentation must be updated in the same change set whenever a PR changes any of the following:

  • API routes, auth behavior, request or response contracts
  • retrieval logic, ranking logic, or language handling
  • ingestion flow, scraping flow, or background execution behavior
  • wallet, billing, or transaction behavior
  • database schema, policies, or operational queries
  • deployment shape, environment variables, or runtime topology
  • operator workflows, troubleshooting steps, or recovery procedures
  • contributor workflow or documentation governance itself

No backend behavior change is considered review-ready if the active docs still describe the old behavior.

3. Document types and boundaries

Architecture docs

Architecture docs describe the current backend system as it exists now.

They answer:

  • how the current system is structured
  • which components own which responsibilities
  • how runtime, data, retrieval, ingestion, and billing work today

Architecture docs must not describe aspirational future state as if it already exists.

Plan docs

Plan docs describe intended work before or during implementation.

They answer:

  • what change is being proposed
  • why the change is needed
  • scope, sequencing, tradeoffs, and acceptance criteria

Plan docs are issue-scoped. They are forward-looking and may become stale after implementation unless either closed out or superseded by active docs and implementation notes.

Implementation docs

Implementation docs record what was actually delivered for a completed piece of work.

They answer:

  • what changed in the repo and schema
  • rollout or migration notes
  • compatibility constraints
  • verification evidence worth preserving

Implementation docs are the completion record for executed work. They are not a substitute for updating architecture docs and runbooks.

ADRs

ADRs record durable architectural decisions.

They answer:

  • what decision was made
  • why it was chosen
  • what alternatives were rejected
  • what consequences follow from the decision

Use an ADR only when the change affects architecture or long-lived policy. Do not use ADRs for routine task tracking.

Runbooks

Runbooks describe how to operate, validate, recover, deploy, or troubleshoot the current backend.

They answer:

  • how to perform an operational task
  • what commands or endpoints to use
  • how to diagnose or recover from problems

Runbooks must always reflect current repo behavior, not planned workflows.

4. Issue to plan-doc requirement

Every GitHub issue must link to exactly one plan doc under docs/plans/.

Rules:

  • a new issue must not start implementation work until its plan doc exists
  • the issue body must link directly to the owning plan doc
  • one plan doc may support multiple tightly related sub-tasks only if one GitHub issue is the explicit parent issue
  • if scope materially changes, update the linked plan doc before continuing implementation

The plan doc is the documentation anchor for the issue.

5. Completed issue to implementation-doc requirement

Every completed GitHub issue must produce or update exactly one implementation doc.

Rules:

  • the implementation doc must live under docs/implementation/, unless an existing active implementation doc already owns that stream of work
  • the issue must link to the implementation doc before closure
  • if the issue was small, updating an existing implementation doc is acceptable
  • if the issue was substantial, create a new implementation doc

Closing an issue without an implementation record is not allowed.

6. PR review requirements for docs

Documentation must be reviewed as part of the PR, not after merge.

During PR review:

  1. reviewers must verify that the linked issue has a linked plan doc
  2. reviewers must verify that the PR updates the active architecture docs and runbooks affected by the change
  3. reviewers must verify that the PR creates or updates the implementation doc that will satisfy issue closeout
  4. reviewers must reject PRs where docs describe target state instead of actual delivered state
  5. reviewers must reject PRs where historical docs are updated but active docs are left stale

If code changes during review, the docs must be revised in the same PR before approval.

7. Documentation definition of done

Documentation is done only when all of the following are true:

  • the GitHub issue links to one plan doc
  • the completed work has produced or updated one implementation doc
  • all affected active docs under docs/ reflect the merged backend behavior
  • architecture docs describe current reality, not planned future state
  • runbooks reflect the actual operational workflow
  • any relevant ADR is created or updated for architectural decisions
  • reviewers have checked documentation as part of PR approval
  • the docs site still builds successfully

If any of those conditions is missing, the work is not documentation-complete and the issue is not done.

Enforcement rule

For this backend branch, documentation is part of the feature, fix, or operational change itself. It is not follow-up work.