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 for decisions you author yourself:
| Type | What It Captures | Example |
|---|---|---|
| What we’re building | Scope, product, or business decisions — what are we building and why | “We will support multi-tenant SSO in v1 but defer SCIM to v2.” |
| How we’re building it | Technical and architectural decisions — how are we building it (ADR format) | “Use PostgreSQL row-level security for tenant isolation.” |
| How we work | Process, ownership, or operational decisions — how do we work | “Architecture reviews happen weekly on Thursdays via async doc.” |
Picking the right type matters: How we’re building it decisions can be exported as Michael Nygard–style ADR markdown for inclusion in technical documentation; What we’re building and How we work decisions are surfaced in the Initiative PRD and review surfaces but not as ADRs.
There’s a fourth type, Process branch, that you won’t pick yourself — Catalio assigns it automatically to decisions promoted from a process scan. It’s surfaced and queryable like any other decision, but isn’t part of the taxonomy you choose from when authoring one directly.
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. Supersede a decision 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
| Field | Purpose |
|---|---|
| title | Short title for the decision |
| decision_type | What we’re building, How we’re building it, or How we work (plus the system-assigned Process branch for decisions promoted from a process scan) |
| status | Proposed, Accepted, Deprecated, or Superseded |
| context | Background and forces that led to this decision |
| decision | The actual decision text — what was decided |
| rationale | Why this option was chosen |
| alternatives_considered | Other options that were evaluated and not chosen |
| consequences | Known consequences, trade-offs, and follow-on implications |
| question_id | Optional — the Initiative Question that prompted this decision |
| superseded_by_id | The newer Decision that supersedes this one (set when status is Superseded) |
The context, rationale, alternatives_considered, and consequences fields are optional, but for How we’re building it decisions intended for ADR export, populating all four produces a far more useful record.
Export as an ADR
How we’re building it decisions can be exported as an ADR. 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.
What we’re building and How we work decisions cannot be exported as an ADR. They stay on the Initiative PRD and review surfaces.
Supersede Chain
When a decision is replaced, supersede the original with the new decision’s details rather than editing it. Superseding creates the successor and links it in one step — do not create a separate successor first. 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
| Stage | Decisions Focus |
|---|---|
| planning | Capture What we’re building decisions as scope crystallizes; surface How we work choices |
| approval | Every decision except the system-assigned Process branch type must leave Proposed before the initiative can advance to build — the Build gate blocks the transition otherwise |
| build | Architectural How we’re building it decisions accumulate as implementation reveals new choices |
| retro | Review which decisions held up, which were superseded, and what was learned |
Relationships at a Glance
| Related Concept | Relationship |
|---|---|
| Initiative | Decisions belong to an Initiative |
| Initiative Questions | A Question can resolve into a Decision via question_id |
| Predecessor Decision | When a Decision is superseded, the chain links back via superseded_by_id |
Best Practices
Pick the decision type at capture time. What we’re building, How we’re building it, and How we work 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 we’re building it.
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, supersede the previous decision with the new decision’s details 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
Pro Tip: Treat How we’re building it decisions as a candidate ADR backlog. At the end of each Initiative, export the Accepted How we’re building it 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
- 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
