HighFile-scope

Template must include Context, Decision, Consequences, and Status

Every ADR must contain the sections: Context, Decision, Consequences, Status. Allowed Status values: proposed, accepted, deprecated, superseded.

Add to Mesrai Open workspace

Why this matters

Consistent sections make ADRs scannable and allow automation to validate lifecycle.

Bad vs. good

Side-by-side examples engineers can pattern-match during review.

Avoid

# ADR: Switch to Redis

We will use Redis.

Prefer

# ADR: Switch to Redis

## Status
accepted

## Context
Cache stampedes on DB.

## Decision
Introduce Redis with TTLs and locks.

## Consequences
Infra cost; add metrics; runbooks.

More snippets

Good

## Status
accepted

Bad

## Notes
We think Redis is nice

Related rules

From the same buckets as this rule.

Critical
Require an ADR for any architectural or cross-team decision
For changes that affect architecture, data models, external APIs, security posture, deployment topology, or cost (>10%), create an ADR in docs/adr/ using the standard template (Context, Decision, Consequences) and link the PR and issue IDs.
docs-adrsmodule-architecture+1
High
Call out breaking changes explicitly
If an API/contract or behavior is breaking, add a 'BREAKING CHANGE' section detailing what breaks, migration steps, and affected consumers.
pr-hygieneapi-contracts-versioning+1
High
Capture security and privacy implications
Add a 'Security & Privacy' section in ADRs addressing threat model impacts, secrets handling, data retention, and PII processing; link to relevant runbooks and DPA if applicable.
docs-adrssecurity-hardening+2

Why this matters

Bad vs. good

More snippets

Related rules

Require an ADR for any architectural or cross-team decision

Call out breaking changes explicitly

Capture security and privacy implications

Why this matters

Bad vs. good

More snippets

Related rules

Require an ADR for any architectural or cross-team decision

Call out breaking changes explicitly

Capture security and privacy implications