state-hub/dashboard/src/docs/decisions.md

---
title: Decisions — Reference
---

# Decisions — Reference

The Decisions page tracks every choice that matters: things pending a verdict, things already resolved, and things that have been escalated for human approval before action can proceed.

---

## Decision types

| Type | Meaning |
|---|---|
| **pending** | A question or fork that still needs an answer — actively blocking or influencing work |
| **made** | A resolved choice; kept for historical context and to explain why things are the way they are |

---

## Decision statuses

| Status | Border | Meaning |
|---|---|---|
| **open** | blue | Pending, no urgent flag |
| **escalated** | amber | Requires human approval before any action (constitution §4) |
| **resolved** | green | Decision has been made and recorded |
| **superseded** | gray | Replaced by a newer decision |

Decisions are sorted by status (escalated → open → resolved → superseded), then by deadline (earliest first within the same status group).

---

## Resolution History chart

An area + step chart showing cumulative decisions over time. Each dot marks a period where at least one decision was recorded or resolved.

**Period selector** — choose the time window:

| Period | Bucket | Use for |
|---|---|---|
| day | hour | Today's activity |
| week | day | Rolling 7 days |
| month | week | Current calendar month |
| quarter | month | Current quarter |
| YTD | month | Year to date |
| year | month | Rolling 12 months |
| all | month | Full history |

The chart respects the active filter — changing type, status, or search narrows the data plotted.

---

## Filter bar

| Filter | Effect |
|---|---|
| **Type** | Show only `pending` or `made` decisions |
| **Status** | Show one or more of open / escalated / resolved / superseded |
| **Search** | Case-insensitive substring match on the decision title |

All filters are applied client-side on the last 500 decisions fetched from the API.

---

## Decision cards

Each card shows:

- **Type badge** — amber `pending` or indigo `made`
- **Status badge** — colour-coded (see table above)
- **Domain** — which of the six tracked domains this decision belongs to (if linked to a topic)
- **Due date** — shown in red with ⚠ if the deadline has passed
- **Age badge** — `open Xd` for unresolved decisions; `took Xd` for resolved ones. Turns amber when an open decision has been open longer than the current average resolution time.
- **Created date** — when the decision was first recorded
- **Title** — the decision question or statement
- **Description / rationale** — first 200 characters, truncated with `…`
- **Resolved by** — who resolved it and when (resolved decisions only)
- **Escalation note** — amber panel explaining why human approval is required (escalated decisions only)

---

## Decision Health card

The **Decision Health** widget in the right margin shows two KPIs computed from the full (unfiltered) dataset:

| KPI | How it's calculated |
|---|---|
| **avg resolve** | Mean time from creation to resolution, computed over the last 5 resolved decisions |
| **avg open age** | Mean age of all currently open or escalated decisions |

**Color coding for avg open age:**

| Color | Condition |
|---|---|
| black (inherit) | All open decisions younger than the avg resolve time |
| amber | At least one open decision older than the avg resolve time |
| red | Mean open age exceeds the avg resolve time |

---

## Escalation

Any `pending` decision whose title or rationale contains financial or legal keywords is automatically escalated by the API at creation time. Escalated decisions:

- Sort to the top of the list
- Carry an amber escalation note explaining the reason
- Trigger the warning box at the bottom of the page listing all escalated items
- **Must be reviewed and approved by the human before any related action is taken (constitution §4)**

To clear an escalation, resolve the decision via `resolve_decision()` in the MCP server or the REST API.

---

## Adding decisions

Via MCP:

```
record_decision(
  title         = "Should we use Redis or Postgres for session storage?",
  decision_type = "pending",
  workstream_id = "<uuid>",
  rationale     = "Postgres is already in the stack; Redis adds a dependency",
  deadline      = "2026-03-01"
)
```

Via REST:

```bash
curl -X POST http://127.0.0.1:8000/decisions/ \
  -H "Content-Type: application/json" \
  -d '{"title": "…", "decision_type": "pending", "workstream_id": "<uuid>"}'
```

---

*Decisions are never deleted — only resolved or superseded (constitution §5).*