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

---
title: Suggestions (legacy) — Reference
---

# Suggestions (legacy) — Reference

The **suggestion** entity is **read-only legacy**. It predates the fleet
**work-record** model. Gated needs, findings, and unvetted sparks are recorded
as **intake** work records (`kind: intake`), not as suggestions.

| Use | Path |
|-----|------|
| **Current** | [Intakes](/docs/intakes) · `POST /intakes/` · MCP `create_intake` |
| **Canon** | `the-custodian/canon/standards/work-record-types_v0.1.md` |
| **Legacy table** | `GET /suggestions/` (historical rows may remain) |

Umbrella: [Work Records](/docs/work-records).

---

## What still exists

| Surface | Behaviour today |
|---------|-----------------|
| `GET /suggestions/` | Lists historical suggestion rows (if any). Ranking query params still exist on the read path. |
| `GET /suggestions/{id}` | Read one historical row. |
| Mutation routes (`POST /suggestions/`, vet, decline, promote, bump-relevance) | **HTTP 410 Gone** — body points at `/intakes/` and the work-record standard |
| MCP `create_suggestion`, `vet_suggestion`, `decline_suggestion`, `promote_suggestion_to_task`, `bump_suggestion_relevance` | Call the retired mutation endpoints; they return 410 |
| Dashboard **Suggestions** page | Still polls `GET /suggestions/?rank=wsjf`; useful only for residual history |
| `GET /state/summary` → `ranked_suggestions` | Still computed from open suggestion rows; after migration the open set is typically empty |

Records were not deleted at retirement. Open backlog at cut-over (2026-07-21,
CUST-WP-0061-T06) was re-authored as file-backed intakes (with
`origin: legacy-suggestion:<uuid>`) and the hub suggestion rows were closed in
place so history remained inspectable.

---

## Former stage model (historical)

While mutations were live, stages were:

| Stage | Meaning |
|-------|---------|
| `suggestion` | Recorded need, not yet vetted |
| `requirement` | Vetted with structured fields and notes |
| `promoted` | Became a real `Task` (`promoted_task_id` set) |
| `declined` | Rejected; terminal |

WSJF ranking used `base_value`, `relevance`, `job_size`, and
`relevance_weight`. That ranking applied only to the suggestion table; it is
not the intake ranking model.

---

## Mapping to intake

| Suggestion concept | Intake equivalent |
|--------------------|-------------------|
| Create gated need | `POST /intakes/` / `create_intake` |
| Vet | Move toward `vetted` / notes on the intake |
| Promote to task | `route_intake` then `statehub promote-intake … --to task` (or workplan / decision / engagement) |
| Decline | `close_intake(outcome="declined")` |
| Absorbed by existing work | `close_intake(outcome="absorbed")` |
| Domain-scoped row | Intake scoped by `topic_id` and/or `workplan_id` and/or `repo_id` |

Do not open new work through the suggestion API.

---

## Related pages

- [Intakes](/docs/intakes) — current entity and lifecycle
- [Work Records](/docs/work-records) — kind registry
- [WSJF Triage](/docs/wsjf-triage) — daily advisory triage (workplan-oriented)

---

*Suggestion mutations are retired by design (CUST-WP-0061). Intake is a fresh
entity, not a rename of the suggestions table.*