Decisions

A Decision is a formally captured choice made during an Initiative. Where Initiative Questions track open unknowns awaiting resolution, Decisions record the resolved outcome — what was decided, why, and what the team considered before choosing. Decisions create a permanent, queryable record of significant choices that would otherwise live in Slack threads, meeting notes, or someone’s head.

A Question can resolve into a Decision: when an open question is answered with a structural choice (architecture, scope, ways of working), link the resulting Decision back to the originating Question to preserve the chain of reasoning.

Decision Types

Catalio uses a three-value decision taxonomy:

Picking the right type matters: :how decisions can be exported as Michael Nygard–style ADR markdown for inclusion in technical documentation; :what and :way_of_working decisions are surfaced in the Initiative PRD and review surfaces but not as ADRs.

Status Lifecycle

Decisions follow a four-state lifecycle:

proposed → accepted → deprecated
                    ↘ superseded → (links to successor)

proposed — The decision has been drafted but is not yet ratified (default on create). Use this when the team has chosen but the choice is still pending review or sign-off.

accepted — The decision is in effect and the team is operating under it.

deprecated — The decision is no longer applicable but has not been replaced by a specific successor. Use this when the context that motivated the decision has changed.

superseded — The decision has been formally replaced by a newer Decision. The successor’s ID is stored in superseded_by_id, creating a queryable history chain. Use the supersede_decision/3 domain helper to perform this transition atomically — it creates the successor Decision and updates the predecessor’s status and superseded_by_id in a single transaction.

Key Fields

The context, rationale, alternatives_considered, and consequences fields are optional, but for :how decisions intended for ADR export, populating all four produces a far more useful record.

ADR Export for :how Decisions

Decisions with decision_type: :how can be exported as Michael Nygard–style Architecture Decision Record (ADR) markdown via Catalio.Initiatives.export_decision_adr/2. The exported document follows the conventional ADR structure:

# <Decision Title>

*Initiative: <Initiative Name>*

## Status

<status>

## Context

<context field>

## Decision

<decision field>

## Consequences

<consequences field>

This makes it easy to publish ADRs into a technical documentation site, an architecture repository, or alongside source code without re-typing the decision.

Decisions of type :what or :way_of_working cannot be ADR-exported — the helper returns {:error, :not_adr_type} so calling code can route those decisions through a different surface (e.g., the PRD narrative).

Supersede Chain

When a decision is replaced, create the successor as a new Decision and use supersede_decision/3 rather than editing the original. Editing destroys the historical reasoning; superseding preserves it as a chain that anyone can walk backward from “what we do today” to “what we used to do and why we changed it.”

The successor inherits the predecessor’s initiative_id and is created in :proposed status by default. The predecessor’s status is set to :superseded and its superseded_by_id points to the successor — atomically, in a single transaction.

Decisions in the Initiative Lifecycle

Relationships at a Glance

Best Practices

Pick the decision type at capture time. :what, :how, and :way_of_working are not interchangeable. The type determines how the decision is surfaced (PRD vs. ADR), how it should be written, and who the audience is. Don’t default everything to :how.

Write context before decision. A decision read without its forces is uninterpretable a year later. Spend two sentences on what made this choice necessary before stating the choice itself.

Capture alternatives considered, even briefly. Listing rejected options is the single highest-value thing you can do for a future reader who is questioning the current state. “We considered X but rejected it because Y” prevents wasted re-litigation.

Supersede, don’t edit, when a decision changes. Editing destroys history. If the team has decided to do something different, create a new Decision and use supersede_decision/3 so the old reasoning remains queryable.

Link Decisions back to the Question that prompted them. When you resolve a Question with a Decision, set question_id so the resolution chain is explicit. The Question’s resolution_text plus the linked Decision’s rationale together tell the full story.

Use :proposed deliberately. A decision in :proposed status is a draft awaiting ratification. Move it to :accepted once the team has signed off — leaving everything :proposed makes the lifecycle meaningless.

Next Steps

• Track Open Questions — Capture the unknowns that Decisions ultimately resolve
• Understand Initiatives — Learn the stage lifecycle that Decisions participate in
• Add Narrative Context — Use Narrative Blocks for free-form context that Decisions reference

Pro Tip: Treat :how decisions as a candidate ADR backlog. At the end of each Initiative, export the :accepted :how decisions and merge them into your architecture documentation — the friction-free ADR pipeline is one of the biggest payoffs of capturing decisions structurally.

Support

• Documentation: Continue reading about Initiative Questions and Narrative Blocks
• In-App Help: The AI assistant can surface Decisions from Initiative context
• Email: support@catalio.ai
• Community: Share decision-capture patterns with other Catalio users