# The Golden Thread

> The foundational mental model, feedback through to outcomes, with every step traceable in both directions.

Source: https://productos.ca/documentation/guides/concepts/golden-thread (last reviewed 2026-09-22)

The Golden Thread is the single most load-bearing idea in ProductOS. Every entity, every API route, and every AI prompt is shaped by it.

## The thread, end to end

A piece of customer feedback travels through six entity types before becoming a measurable outcome:

```
Feedback → Themes → Features → Initiatives → Releases → Outcomes
```

Each arrow is a real, queryable junction in the database, not a vibe. You can walk it either direction:

- **Downstream** from a piece of feedback: *which features did this turn into, and which initiatives did those roll up to?*
- **Upstream** from an outcome: *which feedback contributed to this win, and what themes was it part of?*

The API route `GET /api/v1/golden-thread/{entity}/{id}` walks the graph for you (two hops each way by default, `?depth=` up to 5), and the MCP `get_golden_thread` tool returns the same tree. In the app, the [Golden Thread page](https://productos.ca/documentation/pages/overview/golden-thread) draws the whole graph and lets you walk it from any node.

## Why each level exists

The thread isn't just decorative. Each layer answers a different question, for a different audience, on a different cadence.

| Layer | Question it answers | Audience | Cadence |
| :--- | :--- | :--- | :--- |
| **Feedback** | What is one user saying? | PMs, support | Continuous |
| **Themes** | What are *many* users saying together? | PMs, leadership | Weekly |
| **Features** | What are we going to build to address that? | PMs, engineering | Sprint |
| **Initiatives** | Why are we building this group of features? | Leadership | Quarterly |
| **Releases** | What ships together, and when? | Engineering, GTM | Sprint to quarterly |
| **Outcomes** | Did it work? Did the metric move? | Everyone | Post-release |

Collapse two layers and you lose information. Skip outcomes and you stop learning. The thread is the system.

## The data model under the hood

Each entity has a stable sequence ID prefix you'll see throughout the UI, API, and AI prompts:

- `FDBK-NNNNNN`: Feedback
- `THM-NNNNNN`: Themes
- `FEAT-NNNNNN`: Features
- `INIT-NNNNNN`: Initiatives
- `REL-NNNNNN`: Releases
- `OUTC-NNNNNN`: Outcomes

The bidirectional links are junctions managed via `/api/v1/{entity}/{id}/links/{junction}`, where `{junction}` is the linked entity's slug (`themes`, `features`, `initiatives`, `releases`, `feedback`). Outcomes are the one exception: each outcome points at a single initiative (and optionally a release) through `initiative_id` / `release_id` columns rather than a junction. The [API reference](https://productos.ca/documentation/api/v1/reference/feedback) lists every junction per entity.

> **Many-to-many everywhere**
>
> There are no hierarchical parent/child relationships in the Golden Thread. A single piece of feedback can belong to multiple themes; one feature can roll up to multiple initiatives; one initiative can include multiple releases. Only outcomes are to-one, each belongs to one initiative. This is intentional, real product work doesn't fit a tree.

## How AI fits in

The whole point of grounding ProductOS's AI in your workspace data (vision, OKRs, themes, features, repos) is that the AI can *walk the Golden Thread for you*. When you ask the copilot "why are we building the design tokens v2 initiative?" it pulls:

1. The initiative's stated hypothesis and success metric
2. The themes the initiative was created from
3. The aggregated feedback under those themes
4. The features rolled into the initiative
5. Any outcome data from prior releases on the same initiative

…and synthesizes the answer with citations back to specific `FDBK-`, `THM-`, `FEAT-` IDs. You can click any citation to deep-link into the source.

## Drift and decay

The thread only holds value if it stays current. What the app gives you:

- The **Dashboard** counts live work that isn't moving (blocked features, or high-priority in-flight features with little progress) and shows it as *at risk*.
- **Outcomes** carry a `review_due_date`; use it to schedule the follow-up measurement.
- **ProductSense** does the sweep: *Suggest missing links* finds feedback without a theme, themes without a feature and features without an initiative; *Align statuses* flags a shipped release whose outcome is still pending; *Find orphans* catches abandoned drafts.

There are no configurable decay thresholds or automatic decay alerts yet.

## Where to go from here

- [Connect a source of feedback](https://productos.ca/documentation/guides/getting-started), feedback is the upstream of everything.
- [REST: `GET /api/v1/golden-thread/{entity}/{id}`](https://productos.ca/documentation/api/v1/authentication), for dashboards and analytics.
- [Feedback entity reference](https://productos.ca/documentation/api/v1/reference/feedback): fields, filters, junctions.