# Decision

URL: /business/nouns/decision · Id: `noun:decision`

> A Decision is the immutable record of a choice: its options, the choice, the reason, who decided, and the stakes.

A Decision is the immutable record of a choice: its options, the choice, the reason, who decided, and the stakes. A newer Decision supersedes it, and both stay on record.

## Properties
| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `choice` | `text` | Yes | What was chosen. |
| `reason` | `text` | Yes | Why it was chosen. |
| `stakes` | `string` | No | One of `low`, `medium`, or `high`, which sets the delay window. |

## Object
```json
{
  "$id": "https://api.sb/tutorloop.com/decisions/decision_1",
  "$type": "Decision",
  "choice": "Example choice",
  "reason": "Example reason",
  "stakes": "low"
}
```

## Relationships
- <a id="rel-changes"></a>A Decision **has** many [Changes](/business/nouns/change): every merged [Change](/business/nouns/change) traces back to the Decision that authorized it. `changes`, inverse [`implementsDecision`](/business/nouns/change#rel-implements-decision).
- <a id="rel-decides"></a>A Decision **decides** one [Thing](/business/nouns/thing): a Decision records one choice about a [Thing](/business/nouns/thing) and stays on that Thing’s record forever. `decides`, inverse [`decidedBy`](/business/nouns/thing#rel-decided-by).
- <a id="rel-made-in"></a>A Decision **is made in** one [Meeting](/business/nouns/meeting): a [Meeting](/business/nouns/meeting) records Decisions, each with its options, choice and reason. `madeIn`, inverse [`produces`](/business/nouns/meeting#rel-produces).
- <a id="rel-records"></a>A Decision **records** one [Demand Budget](/business/nouns/demand-budget): each [Demand Budget](/business/nouns/demand-budget) is committed as one Decision, read again when it closes. `records`, inverse [`recordedAs`](/business/nouns/demand-budget#rel-recorded-as).

## Lifecycle

| State | Meaning | Moves to |
| --- | --- | --- |
| `standing` (first) | It is the choice in force. | `superseded` by [Decision.supersede](/business/nouns/decision/supersede) |
| `superseded` | A newer Decision replaced it; both stay on record with the reason for the change. | None: it ends here. |

## Verbs
| Verb | Description | Subject | Event | Class |
| --- | --- | --- | --- | --- |
| [Decision.supersede](/business/nouns/decision/supersede) | Supersede replaces a Decision with a newer one, keeping both on record with the reason for the change. | [Strategist](/agents/founding/strategist) | [`Decision.superseded`](/business/events/Decision.superseded) | None. |
| <a id="create"></a>[Decision.create](/business/nouns/decision/create) | Creates a Decision. Inherited from [Noun](/business/nouns/noun). | None. | `Decision.created` | Two-way: `try`, `send`, `do` |
| <a id="get"></a>[Decision.get](/business/nouns/decision/get) | Returns one Decision by id. Inherited from [Noun](/business/nouns/noun). | None. | None. | Read: `try`, `do` |
| <a id="list"></a>[Decision.list](/business/nouns/decision/list) | Returns Decisions, newest first, one page at a time. Inherited from [Noun](/business/nouns/noun). | None. | None. | Read: `try`, `do` |

A Decision is kept forever and never edited: it has no `update` or `delete`.

## Permissions
Which Access level may call each Verb. One-way Verbs wait their delay window.

| Operation | `owner` | `admin` | `member` | `viewer` |
| --- | --- | --- | --- | --- |
| `Decision.create` | Yes | Yes | Yes | No |
| `Decision.get` | Yes | Yes | Yes | Yes |
| `Decision.list` | Yes | Yes | Yes | Yes |
| `Decision.supersede` | Yes | Yes | Yes | No |

## Call it

**Ask**

```text
Supersede the latest decision.
```

**API**

```bash
curl -X POST https://api.sb/petpantry.shop/decisions/decision_1/supersede \
  -H "Authorization: Bearer $STARTUP_BUILDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"by":"decision_1"}'
```

```json
{
  "api": "https://api.sb/petpantry.shop",
  "decision": {
    "$id": "https://api.sb/petpantry.shop/decisions/decision_1",
    "$type": "Decision",
    "choice": "Example choice",
    "reason": "Example reason"
  },
  "action": {
    "$id": "https://api.sb/petpantry.shop/actions/action_1",
    "operation": "Decision.supersede",
    "status": "done"
  },
  "links": {
    "self": "https://api.sb/petpantry.shop/actions/action_1"
  }
}
```

**SDK**

```ts
import { $ } from 'startup-builder'

const decision = await $.Decision.supersede({ decision: 'decision_1', by: 'decision_1' })
```

**CLI**

```bash
npx startup-builder do Decision.supersede --json '{"decision":"decision_1","by":"decision_1"}'
```

**MCP**

```json
{
  "name": "do",
  "arguments": {
    "code": "return await $.Decision.supersede({ decision: 'decision_1', by: 'decision_1' })"
  }
}
```

## Example
The [Founder](/agents/founding/founder) picks usage pricing over per-seat pricing. The Decision records both options, `choice: usage`, the `reason` ("[Customers](/business/nouns/customer) already pay per call"), and `stakes` of $40,000 a year.