Decision-Governed Shipping Template (copy/paste)

1) Architecture Decision Record (ADR) — use for any change that affects behavior, data shape, reliability posture, security, or vendor lock-in.

ADR Title:
Date:
Owner (accountable person):
Status: Proposed / Accepted / Superseded
Links: ticket, incident(s), PR(s), dashboards

Context (5-10 lines):
- What triggered this decision?
- What constraints are real (latency, compliance, cost ceiling, staffing, deadlines)?

Decision (one sentence):
- We will…

Assumptions (bullets):
- What must be true for this to work?
- What are we assuming about load, ordering, permissions, data quality, dependencies?

Alternatives considered (at least 2):
A) … Pros / Cons
B) … Pros / Cons

Consequences (be honest):
- What gets worse?
- What becomes harder later?
- What new failure modes did we introduce?

Reversibility plan:
- What would make us revert?
- Exact rollback steps (flag off, revert commit, migration strategy)
- “Point of no return” (if any) and how we avoid it

2) PR Evidence Block — paste into every PR description.

## Evidence
Change type: Refactor / Behavior change / Schema-migration / Security-auth / Hot-path reliability

Tests:
- What tests were added/updated?
- Link to CI run(s):

Observability:
- Dashboard link(s):
- New/changed metrics/logs/traces (names):
- What alert would fire if this regresses?

Rollout plan:
- Feature flag? (name + default state)
- Canary or staged rollout steps:

Rollback plan:
- Exact steps to undo:
- Data rollback considerations:

Risk notes:
- If I’m wrong, what breaks?
- Worst-case customer impact:

Assumptions (repeat the important ones):
- …

3) Review Prompts (for reviewers)
- What user-visible behavior changed and how will we detect regressions?
- What happens on partial failure (timeouts, retries, duplicate events, out-of-order messages)?
- What invariants are we relying on, and are they enforced by code/tests/runtime checks?
- Is the rollback actually safe under real traffic and real data?

How to roll this out in a team:
- Pick one gate to enforce for 30 days (flags for behavior changes is a strong start).
- Make non-compliance a merge blocker.
- Keep ADRs short; make reversibility and assumptions mandatory.