Reversible / agile6 sections · ~200–400 words

Agile ADR

Hybrid (Atlassian, ThoughtWorks, IndustrialLogic patterns)

Decision + alternatives + a 'review by' date. Built for teams that revisit calls every quarter and want the ADR to remind them.

Use it when

The decision has a known shelf life — a vendor contract, a build-vs-buy that depends on team size, a temporary workaround.
You want the ADR to actively prompt a re-review, not be a tombstone.
Your team treats decisions as reversible by default and wants the format to reflect it.

Avoid when

Truly permanent decisions — adding a 'review by' date is a lie that ages badly.
Compliance contexts where decisions are immutable for audit reasons.

Strengths

The Review-By field is the killer feature: it's a calendar entry disguised as a heading.
Encodes reversibility explicitly, which is what most teams forget.
Pairs naturally with quarterly architecture reviews.

Weaknesses

Review-by dates rot. If nobody owns the calendar, the field becomes noise.
Some teams use 'reversible' as a license to underthink the decision.

Sections

6 required · 0 optional

Treats decisions as time-bound. Pairs with quarterly review cadences.

Title

Required

ADR-NNN: short noun phrase.

ADR-0023: Use Render for the staging environment

02
Status
Required
Active | Superseded | Expired (the review-by date passed without a re-review).
```
Active — review by 2026-09-01
```
03
Reversibility
Required
Two-way (we can walk this back) | One-way (we can't). Be brutally honest.
```
Two-way — migration to a different host estimated at <1 sprint.
```

Decision

Required

What we will do.

Use Render for the staging environment, deployed via the existing GH Action.

Alternatives

Required

What we didn't pick, in one bullet each. Don't oversell — a clipped reason is fine.

- Vercel Preview Deployments (would conflate staging with preview).
- Self-managed k8s on Hetzner (no — staging shouldn't be a project).

06
Trigger to revisit
Required
What event would make us re-open this. Specific. 'When we hit X' or 'on the next quarterly review'.
```
Revisit when staging exceeds $200/mo on Render, or at the 2026-Q3 architecture review.
```

Worked example

A real ADR written in the Agile format. Copy the markdown and adapt it.

ADR-0023: Use Render for the staging environment

Status

Active — review by 2026-09-01

Reversibility

Two-way. Migration to a different host (Vercel, Fly, Railway) is estimated at less than one sprint. Staging has no persistent customer data; environment variables are the only state to migrate.

Decision

Use Render for the staging environment of the operator console, deployed via the existing GitHub Action on every merge to main.

Alternatives

Vercel Preview Deployments. Would conflate staging with preview;

every PR would generate a 'staging' that's actually ephemeral. Wrong semantics for the QA team.

Self-managed Kubernetes on Hetzner. No — staging shouldn't be its

own infrastructure project at our scale.

Fly.io. Solid alternative; lost on price predictability for a

staging workload that idles overnight.

Trigger to revisit

Revisit when staging exceeds $200/mo on Render, or at the 2026-Q3 architecture review — whichever comes first.

Field of application

Honest accounts of where this template was the right shape — and where it wasn't.

Context
Picking a staging-environment host where the team's needs will probably change.
Outcome
Review-by date triggered the re-decision exactly when expected (Q3). The 'two-way' tag in Reversibility kept the team from over-investing in custom Render-specific tooling.
Context
Choosing the database for a long-lived production system.
Outcome
Wrong shape. The 'review-by' field was a lie — the team would never realistically re-host. Should have been Nygard or Tyree-Akerman.

Tags:reversible review by lightweight