DecisionRecord

A significant choice — architectural, product, or process — recorded with its context, rationale, and alternatives. The ADR (Architecture Decision Record) pattern as a first-class entity.


ID prefix	`DEC`
State machine	`decisionrecord`
MCP server	`decision-record`
Skill	`decision-record` (Layer 2)

State machine

proposed → accepted → superseded
         ↘ rejected

accepted, rejected, and superseded are terminal.

Fields

Required

Field	Type	Description
`title`	string (1–200)	Short declarative title
`state`	string	Current state
`decision`	string	The chosen option, stated clearly

Optional

Field	Type	Description
`context`	string	Situation that prompted the decision
`rationale`	string	Why this option was chosen
`alternatives`	object[]	Each with `option` (required) and `rejected_because` (optional)
`consequences`	string	Known or expected downstream effects
`deciders`	`ACTOR-*[]`	People / agents who made the decision
`supersedes`	`DEC-*`	Prior decision this replaces
`superseded_by`	`DEC-*`	Later decision that replaces this one
`related_workitems`	`BACK-*[]`	Work items that motivated or implement this decision
`decided_at`	datetime	When the decision was finalised

Example

---
apiVersion: processkit.projectious.work/v1
kind: DecisionRecord
metadata:
  id: DEC-20260411_0902-SwiftPeak-sqlite-for-index
  created: '2026-04-11T09:02:00Z'
spec:
  title: Use SQLite as the entity index store
  state: accepted
  decision: Use SQLite with WAL mode as the backing store for the index.
  context: |
    We need a queryable index over all context/ entities that agents can
    use without doing filesystem walks.
  rationale: |
    SQLite is zero-config, ships as a Python built-in, and supports
    full-text search via FTS5. No external service needed.
  alternatives:
    - option: PostgreSQL
      rejected_because: Requires a running service; too heavy for local dev.
    - option: DuckDB
      rejected_because: No built-in full-text search; adds a dependency.
  decided_at: '2026-04-09T12:00:00Z'
---

Notes

Use supersede_decision to create a clean supersession chain when a decision changes — the old record stays as history, the new one links back via supersedes.
Link decisions to work items with link_decision_to_workitem to make the “why was this built?” trail queryable.
proposed is the right starting state for decisions that need stakeholder sign-off before being acted on.