Every priority queryable to its rationale.

Twelve months after a priority decision, when the board asks why Initiative A was funded over Initiative B, the answer should not be “because the VP wanted it” or “I think we discussed this in the April planning session.”

The answer should be: here are the criteria that were selected and locked. Here are the values that were accepted and by whom. Here is the session result. Here is the Catchball exchange. Here is the governance event that authorized it. All of it, on the record, queryable via API.

That is what decision traceability produces.

The decision record

Every significant governance event in Priorities.ai automatically writes a decisions row. Every decision is typed, linked to its source event, and linked to the objects it affected.

Decision classes:

Class	Description	Typical trigger
`force_ranking`	A strict total ordering was produced	Session published, Priority list approved
`selection`	A bounded set was chosen from candidates	Criteria finalized, Item pool curated
`convergence`	Uncertain or disputed values were resolved	Catchball proposal accepted
`range_selection`	Ranges, bands, or thresholds were established	Scale definitions confirmed
`review`	Structured comparison without total ordering	Review sessions

Auto-recorded decisions

These events automatically write a decision record:

Event	Class	Impact
Session reaches `PUBLISHED`	`force_ranking`	High
Session reaches `CRITERIA_FINALIZED`	`selection`	Medium
Priority list approved	`force_ranking`	High
Catchball proposal accepted	`convergence`	Medium

Each auto-decision carries: title, body (generated), decision class, impact, source event ID, linked objects (items, sessions, cycles), actor, and timestamp.

Auto-decisions are immutable. Their back-links to source events and linked objects cannot be altered after creation.

Manual decisions

Users can record any organizational decision — the kind that happens in a conversation, a board meeting, a one-on-one — directly in Priorities.ai.

A manual decision carries:

Title and rationale body
Decision class
Impact (high, medium, low)
Related objects (items, sessions, cycles, tracks — any combination)
Tags
The decider (defaults to current user, can be set to anyone)
Decided-at timestamp (can be backdated)

Manual decisions sit in the same decision log as auto-decisions. An auditor, a board member, or a new executive joining the organization sees a complete timeline — both the decisions the system recorded automatically and the decisions that were recorded by hand.

The event hierarchy

Decision traceability has three layers:

decisions          ← typed, human-readable, manual + auto-recorded
                     linked to source events, queryable by class, impact, status
                     
governance_events  ← major lifecycle actions
                     cycle phase transitions, session publications, pool locks,
                     list approvals — the authoritative governance record
                     
audit_events       ← full per-item trail
                     every event that happened to a specific item:
                     shaped, valued, added to pool, ranked, override applied

These are three distinct tables with three distinct purposes. decisions is the human-readable layer. governance_events is the authoritative lifecycle layer. audit_events is the per-item forensic layer.

Read models

Reports in Priorities.ai are write-once, never recomputed. A session report generated today is identical to the same session report generated at audit time a year from now — because it reads from the immutable result records, not from the mutable source tables.

This is a critical architecture decision. The value of a decision record is precisely that it cannot change retroactively. A “dynamic” report that recomputes from current state is not provenance — it is a description of current state that happens to look like history.

Available read models:

GET /v1/reports/sessions/:id — session report with all result records
GET /v1/reports/cycles/:id — cycle report with all tracks and session states
GET /v1/reports/items — up to 500 items with full field data (JSON or CSV)

Decision status lifecycle

A decision record has a status that allows organizations to manage the decision record over time without altering the underlying fact:

active → superseded  (a newer decision takes precedence — the old one still exists)
active → reversed    (the decision was undone)
superseded → active  (reinstate)
reversed → active    (reinstate)

The underlying decision record — the criteria, the values, the session result, the source event — is never altered. Only the status changes.

Developer access

# Webhook events available today:
#   session.published
#   cycle.transition
#   priority_list.approved

# Subscribe to decision events
POST /v1/webhooks
{
  "name": "Decision Notifier",
  "url": "https://your-endpoint.example.com/priorities",
  "events": ["session.published", "priority_list.approved"]
}

Note (Coming soon): GET /v1/decisions, GET /v1/governance-events, and GET /v1/audit-events are planned API endpoints. The underlying data is captured and stored today — the public read surface is on the roadmap.

Decision Traceability