tegwick
d8a2bb5c6b
Align dashboard reference pages with intake-as-discovery and suggestions as legacy, frame work records as unit vs structure artefacts, and add the ready STATE-WP-0076 plan for DoC/DoR quality policies. Include generated work-record index and recent legacy-meter evidence captures.
3.1 KiB
| 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 · 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.
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 — current entity and lifecycle
- Work Records — kind registry
- 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.