Open app →

Writing an ADR

An Architecture Decision Record (ADR) captures one significant decision: the context, the choice, the alternatives you weighed, and the consequences. In ArchForge, decisions live under Decisions in the sidebar and get reference IDs like ADR-0042.

Decisions are available on every plan. You need the Member role or higher to write one.

1. Start a draft

  1. Open Decisions in the sidebar.
  2. Click + New Decision.
  3. Enter a Title that states the decision, for example Use Postgres row-level security for tenant isolation.
  4. Add any co-authors under Authors with + Add.
  5. Fill in the Body (Markdown), then click Create draft.

You can also start a decision from a closed RFC with Build Decision. The RFC's content is copied into a new draft decision, which links back to the RFC. See Running an RFC.

2. Write the decision

The body starts from your workspace's decision template. The built-in template has these sections:

  • Context: the forces at play and the problem that makes this decision necessary.
  • Decision: what you're going to do, in full sentences and active voice. A good decision reads as an imperative: We will use Postgres row-level security for tenant isolation.
  • Alternatives considered: the options you didn't choose, and why.
  • Consequences: what becomes easier or harder, including risks and follow-up work.

Keep it short and specific. Use Context to explain why the decision matters now, and be honest in Consequences about what the choice costs.

Your administrator may have tailored this template. See Artifact types and templates.

The template also starts with a Status heading. That text is just part of the body; the real status is the one shown under the title, which ArchForge manages for you.

While the decision is a Draft, click Edit to change it as often as you like. Each save creates a new version.

3. Propose it for review

When the decision is ready:

  1. Click Propose for review.
  2. Under Choose a reviewer, search by name or email and pick a reviewer. Only members with the Reviewer or Admin role are listed.

The decision moves to Proposed, the reviewer's name appears under the title, and the reviewer is notified in the app and by email. While it's proposed, the content is locked.

4. Respond to the review

The reviewer can:

  • Accept it. The decision becomes Accepted, the authoritative record.
  • Reject it. The decision becomes Rejected and is kept for the record.
  • Request changes. The decision moves to Changes Requested with a checklist of what to fix.

If changes are requested, the checklist appears at the top of the page under Requested changes. Edit the decision, tick each item off as you address it, then click Resubmit for review. It goes straight back to the same reviewer.

Every round is recorded on the Review history tab. For the full picture, see Reviewing and approving.

5. Keep it current

Decisions are never deleted. When an accepted decision is overtaken by events, open it and click:

  • Supersede, when a newer decision replaces it.
  • Deprecate, when it no longer applies and nothing replaces it.

The history stays intact, so anyone asking "why did we do it this way?" can still find the answer.