Skip to content

Issue Lifecycle

Purpose

Backend issues must move through a documentation-governed workflow. Every issue needs a planning record before implementation and an implementation record before closure.

See documentation-policy.md for the governing rules.

Required lifecycle

  1. Intake Capture the backend problem, affected services, routes, tables, or operational flows.
  2. Plan Create or identify exactly one plan doc in docs/plans/ and link it from the GitHub issue.
  3. Design Update the plan doc as scope sharpens. Add or update an ADR if the issue changes durable architecture policy.
  4. Implementation Land code, schema, tests, and active docs together.
  5. Review Update docs during PR review whenever code or scope changes. Reviewers must validate plan linkage and doc completeness.
  6. Verification Run the required backend checks and verify the delivered behavior.
  7. Implementation Record Create or update exactly one implementation doc in docs/implementation/ for the completed issue and link it from the issue.
  8. Closeout Close the issue only after active docs, implementation docs, and any needed ADRs are updated.

Required artifacts

Each backend issue must have:

  • one linked plan doc under docs/plans/
  • zero or one ADR update when the issue changes long-lived architecture decisions
  • one created or updated implementation doc under docs/implementation/
  • active documentation updates under docs/ for any changed architecture, runbook, or contributor workflow

PR review workflow

During PR review, confirm all of the following:

  • the issue links to one plan doc
  • the plan doc still matches the implemented scope
  • active architecture and runbook pages reflect the delivered behavior
  • an implementation doc has been created or updated for issue completion
  • Postman artifacts were updated if API routes changed

If review changes the implementation, update the docs in the same PR before approval.

Done criteria

An issue is not done until:

  • code is merged
  • schema changes are accounted for
  • the issue links to one plan doc
  • the completed work has produced or updated one implementation doc
  • active docs reflect the new backend state
  • any necessary ADR has been created or updated
  • route changes are synced to Postman when applicable
  • the docs site builds successfully