[ Concepts · Decisions ]
Decisions
A decision records what the team chose, why it chose it, and what follows from that choice. Decisions can link to affected issues and keep append-only body snapshots so later readers can see how the decision changed.
Agents need more than the current answer. Versioned decisions make architecture and product calls durable, auditable, and easy to propagate to the issues that depend on them.
Shape
- title
- string
- Short name for the choice.
- decision
- string
- The actual choice or policy.
- rationale
- string?
- Why this direction was chosen.
- consequences
- string?
- Tradeoffs, follow-up work, or expected effects.
- status
- proposed | decided | superseded
- Decision state.
- linkedIssueIds
- issueId[]?
- Issues affected by this decision.
- supersededById
- decisionId?
- Replacement decision when status is superseded.
- editCount
- number?
- Count of meaningful body edits.
Lifecycle
- proposed: the choice is being considered.
- decided: the choice is active guidance.
- superseded: a later decision replaced it.
- Every meaningful body edit writes a decision revision.
- When linked issues need attention after a change, decision revalidations track pending, acknowledged, and dismissed propagation state.
How It Appears In MCP / REST
MCP
create_decision({ title, decision, status: "decided" })
get_decision_history({ id })
get_decision_propagation({ decisionId })REST
POST /api/v1/decisions
GET /api/v1/decisions/:id/history
GET /api/v1/decisions/:id/propagation