Decisions
The Decisions page of a project: every choice the project made with its kind, context, the options weighed, what was decided, the consequences, who decided and when, the decision it supersedes, the lifecycle from proposed to accepted and the versions.
By the end of this page you will have recorded the choices a project made as decisions someone can read in a year and still understand; know every field a decision carries and what reads it downstream; and know how a decision moves from proposed to accepted, how a newer decision supersedes an older one, how a decision is deleted, and where every version of it is kept.
A decision is the record of a choice: keep the loyalty ledger in Postgres. It keeps the
context the choice was made in, the options that were on the table with what spoke for
and against each, what was decided, the consequences that follow, who decided and when,
and the earlier decision it supersedes. Decisions number on their own sequence (CRM-DEC-5)
and carry a kind (architecture, product, process, vendor or security) that says who should sit at
the table. The log is internal: a client guest never sees it. Every save of a decision is kept as
a version. The page is the second tab of the RAID family,
beside the RAID log, because the risks and the decisions are read in the
same meeting.
Before you begin
| You want to | You need |
|---|---|
| Open the Decisions tab | decision:view-any on the project, which every staff role carries. A client guest is refused at the door. |
| Record a decision | decision:create. Project managers, business analysts and developers have it by default. |
| Edit or move a decision | decision:update. |
| Delete a decision | decision:delete. |
| Name a decider | The person to be a member of the team. |
The page lives under a project: open the project, choose RAID Log in the sidebar and press the Decisions tab.
Read the decisions
The table lists one decision per row:
| Column | What it shows |
|---|---|
| Reference | The decision's key, painted in the colour of its kind. |
| Decision | The title, with the first line of what was decided beneath it. Press the title to open the flyout. |
| Kind | Architecture, product, process, vendor or security, with the kind's icon. |
| Status | Proposed, accepted, rejected, superseded or deprecated, as a badge. |
| Decided | The day it was accepted, or Not yet. |
| Supersedes | The reference of the earlier decision it replaces, when it names one. |
| Updated | How long ago the record last changed. |
| Row menu | View Decision, Edit Decision, Move to, Activity, Delete Decision. |
Sort by reference, title, kind, status, the day decided or updated by pressing a column heading; press it again to flip the direction. The list opens in the project's own order.
Above the table, narrow the list with the search box (words in the reference or the title), the kind and status lists. The filters travel in the page address, so a filtered list can be shared; Clear Filters on the empty state drops them all.
Record a decision
- Press New Decision.
- Pick the Kind, and under Supersedes the earlier decision this one replaces, if any.
- Type the Title: what was chosen, in one line. This alone is enough; Heimdall will propose the rest.
- Write the Context: the situation and the forces that made a decision necessary.
- Under Options weighed, press Add Option once per option and type what it is, its Pros and its Cons; put the chosen one first.
- Write what was Decided and the Consequences.
- Pick the Deciders from the team and press Record Decision.
The decision takes the next number of the decisions' sequence (the first decision of CRM is
CRM-DEC-1), starts as proposed, appears in the table at once, writes its first version with its
options inside it, and decision.created goes out to every endpoint subscribed to it.
A decision with one option was never a decision
Write down what else was on the table, even the option everyone dismissed in a minute, with the reason it lost. The next person to ask why not the event store? reads the answer instead of reopening the question.
Open a decision
Press a decision's title, or View Decision in its row menu, to open the detail flyout: the reference, kind and status at the top, the title, then the context, the options weighed in order with their pros and cons, what was decided and the consequences side by side, the deciders, the day decided, the decision it supersedes, the dates, and the Versions section with every save of the decision. From the flyout:
- Edit opens the editor on this decision.
- Move to changes the status in one step, offering only the moves the lifecycle allows.
- Restore this version under any earlier version puts it back, options included; see revisions and versions.
- Activity opens the decision's history: every change, who made it and where it came from.
- Delete opens the confirmation.
A link such as /projects/<id>/raid/decisions?show=<decision id> opens the page with that
decision's flyout already open; Heimdall's View buttons use it.
Edit a decision
- Press Edit Decision in the row menu, or Edit in the flyout.
- Change what you need, the option rows included: Add Option appends a row, the arrows reorder the rows and the cross removes one. Every decider must be a member of the team, and a decision cannot supersede itself or one of another project.
- Press Save Changes.
The save writes a new version of the decision, options included, and decision.updated goes out
with the columns that changed, each with its old and new value. An edit that changes nothing
writes nothing and announces nothing. The status does not change from the editor; it moves from
the list or the flyout.
Move a decision along its lifecycle
Move to in the row menu or the flyout offers the moves the lifecycle allows from where the decision stands:
| Status | Meaning | May move to |
|---|---|---|
| Proposed | Put forward with its options; not yet decided. | Accepted, rejected |
| Accepted | Decided and in force; the team builds on it. | Superseded, deprecated |
| Rejected | Turned down; kept so the reasoning is not lost. | Proposed |
| Superseded | Replaced by a later decision that names it. | Accepted |
| Deprecated | No longer applies and nothing replaced it. | Proposed |
A move into Accepted stamps the day it was decided (when none was set) and, when the decision
names an earlier one under Supersedes, moves that one to Superseded in the same breath, so
the log never holds two decisions in force on the same question. Every move writes a version with
the reason moved and decision.status_changed goes out with the status before and after, once
for each decision that moved.
Until the approvals land
A project manager, an analyst or a developer accepts a decision by hand today. The approval module will let the deciders named on the record accept it themselves, with a signature on the version they accepted.
Delete a decision
Delete Decision in the row menu or Delete in the flyout opens the confirmation. Deleting
removes the decision with every version it kept and its activity history; a later decision that
named it keeps its own record and loses the link; its number is never handed out again.
decision.deleted goes out. Prefer Deprecated for a decision that no longer applies: it keeps
the reasoning.
All the fields
What happens next
- Every save, move and restore writes a version, options included, and an entry in the project's activity history.
decision.created,decision.updated,decision.status_changed,decision.restoredanddecision.deletedgo out to the webhook endpoints subscribed to thedecision.*family.- The context pack of a story will carry the accepted decisions it builds on, epics, requirements and components will link to decisions, and Odin in the council will cite them when a design or a change request is reviewed, as those modules land.
Heimdall on this page
Heimdall reads the decisions and their versions through the same tools the MCP server offers, records a decision as proposed when a conversation, a story or a design settles a choice, and carries the open project as its context.
On the editor, Ask Heimdall beside each long field drafts it, improves it, shortens it, makes it testable or rewrites it as Given, When, Then; the draft waits under the field until you take it or drop it. See inline assists.
The brief import will draft the decisions a brief already implies into a review queue, and the meeting notes extraction will record the decisions a meeting took.
From the API and MCP
Decisions API
List, read, add, change, move and delete decisions, and read and restore their versions.
Planning tools
list_decisions, get_decision and record_decision_draft: the MCP tools that read decisions and record a draft.
Permissions
| Action | Permission |
|---|---|
| See the decisions | decision:view-any, decision:view; never a client guest |
| Record a decision | decision:create |
| Edit or move a decision | decision:update |
| Delete a decision | decision:delete |
| Read or restore its versions | decision:view to read, decision:update to restore; never a client guest |
Frequently asked
Related
- Traceability — the Links panel in the flyout: what this implements, verifies, depends on or relates to, read from either side
- Comments and mentions — the Discussion panel in the flyout: questions, answers, mentions, followers
- Attachments — the Files panel in the flyout: wireframes, specifications and samples pinned on the record
- RAID log — the risks and dependencies a decision answers to, on the first tab
- Business rules — the decisions of the business, as opposed to the team's
- Revisions and versions — every save kept, any version put back
- Status reference — every kind and status
decision.*webhook events
How is this guide?
Last updated on
RAID Log
The RAID Log page of a project: risks scored by probability and impact with their mitigation and contingency, assumptions, issues and dependencies, each with its area, owner, dates and status, the risk matrix, the lifecycle and the versions.
Traceability
The Links panel in every artefact flyout: join a story to the requirement it implements, a bug to the story that fixes it, a decision to the epic it shapes, read each link from either side and open the other end.