Writing a decision

RFC or ADR

Use an RFC when you want input before choosing. Use an ADR to record a choice that is already made. Both are the same kind of record in DesignDoc, written in Markdown with a template.

Decision types

Each decision has a kind. You pick it when you create the decision, and it chooses the starting template. The kind can change while the decision is a draft.

Standards usually apply to a whole repository rather than a list of paths. Under Code links, pick Whole repository (the default for a standard) to link one. Every push to that repository then lands in a single drift event for the decision, counted as pushes, instead of opening one event per push; no AI summary is written unless you ask for one from the event. Re-confirm or dismiss the event as usual, and the next push starts a new one.

Exceptions expire. An exception needs an expiry date (at most three years out) before it can go to review. Accepted exceptions appear under Expiring and sunsetting in your queue from 14 days before the date. When the date passes, the exception is marked stale and its author and deciders are notified. From the stale banner, Renew sets a new expiry and Supersedestarts a replacement. Deprecations can carry an optional sunset date that works the same way; when it passes, the notification reads “Sunset passed” rather than “expired”.

What a reviewable decision contains

• Context that a new joiner can follow.
• Alternatives considered, including doing nothing, and why each lost.
• The decision and who owns it.
• Scope and non-goals.
• Risks and rollback: how you would back out and what it costs.
• Success measures and when you will check them.

These are the same things the AI pre-review looks for, so a doc that has them reviews faster.

Statuses

Cross-references

Link a decision to others that it supersedes, depends on or conflicts with. The existing AI review reads these relations when it checks a new decision against earlier ones.