---
title: Intakes — Reference
---

# Intakes — Reference

An **intake** is a work-record kind for a **spark**: an idea, finding,
directive, or request that is not yet a workplan, task, decision, or
engagement. Intakes hold early signal until someone vets, routes, and either
promotes or closes them.

Canon: `the-custodian/canon/standards/work-record-types_v0.1.md`
(`kind: intake`, id scheme `{PREFIX}-IN-NNNN`).
Umbrella: [Work Records](/docs/work-records).

Intakes **replace** the retired hub **suggestion** backlog for new work. See
[Suggestions (legacy)](/docs/suggestions).

**Quality:** discovery comprehension is governed by
[Definition of Comprehension (DoC)](/policy/intake-doc) (`DoC-Ok` /
`DoC-Failed` / unassessed). DoC is independent of lifecycle `status` and is
**not** implementation readiness ([DoR](/policy/work-item-dor)). Model:
`docs/work-record-quality-gates.md`.

---

## Lifecycle

```text
open -> vetted -> routed -> closed(promoted | declined | absorbed)
```

| Status | Meaning |
|--------|---------|
| **open** | Captured; not yet fully vetted |
| **vetted** | Reviewed; structure and intent are clear enough to route |
| **routed** | Assigned a destination / owner path; eligible for promotion |
| **closed** | Terminal; requires an **outcome** |

| Outcome (only when `closed`) | Meaning |
|------------------------------|---------|
| **promoted** | Became another work record; `promoted_to` holds the new canonical id |
| **declined** | Explicitly not pursued |
| **absorbed** | Already covered by existing work; no new record needed |

Database constraints (what the API enforces):

- At least one of `topic_id`, `workplan_id`, or `repo_id` is set (scope).
- `closed` requires `outcome`.
- `outcome = promoted` requires `promoted_to`.

Route action: only from `open` or `vetted` → `routed`.
Close action: from `open`, `vetted`, or `routed` → `closed`.

---

## Fields that matter

| Field | Role |
|-------|------|
| `title` / `description` | Human-readable content |
| `lane` | Autonomy lane: `green` \| `blue` \| `yellow` \| `orange` \| `red` |
| `status` / `outcome` | Lifecycle |
| `origin` / `origin_ref` | Where the spark came from. **Residuals:** `origin: residual` (or `handoff`) and `origin_ref: <parent-WP-id>` (e.g. `BINKY-WP-0006`). Also e.g. `legacy-suggestion:<uuid>`, mail-triage ids |
| `promoted_to` | Canonical id of the record this became after promotion |
| `source_repo_path` | Repo-relative path of the YAML block / file when file-authored |
| `routed_note` | Free-text routing context |
| `notes` | Append-only note list via `POST /intakes/{id}/notes` |

Identity: hub rows use UUIDv7 primary keys. File-backed blocks use fleet ids
such as `CUST-IN-0004` and receive `state_hub_intake_id` write-back from
`fix-consistency`.

---

## How intakes enter the hub

**1. File-backed (preferred for lasting work)**

Author a schema-valid YAML block in any repo markdown file (canon schemas under
`the-custodian/canon/standards/schemas/work-records/`). Commit, then run
`statehub fix-consistency` so the hub registers the record and writes the UUID
back.

**2. Hub API / MCP (capture path)**

```text
create_intake(title=..., topic_id=... | workplan_id=... | repo_id=..., lane="green", ...)
# REST: POST /intakes/
```

```text
list_intakes(status="open")
route_intake(intake_id, routed_note=...)
close_intake(intake_id, outcome="declined"|"absorbed"|"promoted", promoted_to=...)
```

REST mirrors: `GET/POST /intakes/`, `PATCH /intakes/{id}`,
`POST /intakes/{id}/route`, `POST /intakes/{id}/close`,
`POST /intakes/{id}/notes`.

---

## Promotion (intake → another kind)

Promotion is the sanctioned path from a **routed** intake into a durable
work-record kind:

```text
intake.routed  →  workplan | task | decision | engagement
```

Implemented by:

```bash
# via CLI (statehub entrypoint wraps scripts/promote_intake.py)
statehub promote-intake <intake-id-or-uuid> --to workplan --repo <path>
statehub promote-intake <id> --to task --workplan-file workplans/….md
statehub promote-intake <id> --to decision --target-file <md>
statehub promote-intake <id> --to engagement --target-file <md>
```

What the promotion transition does today:

1. Validates the intake is **routed**.
2. Writes the target artefact (ADR-001 workplan file, task block, or
   decision/engagement YAML block).
3. Sets intake `promoted_to` and closes with `outcome=promoted`.
4. Sets `origin: intake:<…>` on the new record for back-link.
5. Registers / syncs with the hub where a hub entity exists.

**Engagements:** promotion can write the file block; a first-class hub
engagement entity is not present yet — the CLI reports that limitation rather
than inventing silent hub rows.

Closing with `outcome=promoted` by hand is supported for after-the-fact
recording, but the promote CLI is the intended path for both artefacts.

---

## What is not wired yet

These are present limitations of the current hub surface (not aspirations):

| Area | Current behaviour |
|------|-------------------|
| **Dashboard** | No dedicated Intakes page yet; legacy [Suggestions](/suggestions) still reads the old table |
| **Next-steps / summary** | `ranked_suggestions` and open-suggestion signals in `GET /state/summary` and `get_next_steps` still read the **suggestion** table, not intakes |
| **WSJF on intakes** | Suggestion WSJF fields (`base_value`, `relevance`, …) are not part of the intake model |
| **Task-flow YAML** | Workplan, task, and contribution have `flows/*.yaml`; intake advances via dedicated route/close endpoints rather than `advance_workstation` |

Use `GET /intakes/` or MCP `list_intakes` for the live backlog.

---

## Residuals as intakes

When a workplan finishes with leftover work that is not large enough for an
immediate child workplan, author an **intake** with:

```yaml
origin: residual
origin_ref: BINKY-WP-0006   # parent workplan id
lane: green                 # or blue/yellow/…
status: open                # or vetted/routed when ready
```

Promote with `statehub promote-intake` when structure is ready (e.g. to a
workplan). Listing open residual intakes across domains is a State Hub read
concern (`list_intakes` + origin filters; planned `statehub residuals` CLI).
See [Work Records — Residuals](/docs/work-records#residuals-role-not-kind).

## Relation to other kinds

| Kind | Boundary |
|------|----------|
| **workplan / task** | Durable planned work; intake is the pre-plan capture form |
| **decision** | Approval package; an intake may promote *into* a decision |
| **contribution** | Outbound third-party artefact — different entity; not an intake outcome |
| **suggestion (legacy)** | Superseded capture mechanism; do not create new ones |
| **residual** | Not a kind — role of intake/WP/decision with `origin: residual` |

---

*Intakes are a fresh entity (CUST-WP-0061), not a rename of `suggestions`.*
