Concepts
The Golden Thread
The foundational mental model, feedback through to outcomes, with every step traceable in both directions.
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 → OutcomesEach 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 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: FeedbackTHM-NNNNNN: ThemesFEAT-NNNNNN: FeaturesINIT-NNNNNN: InitiativesREL-NNNNNN: ReleasesOUTC-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 lists every junction per entity.
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:
- The initiative's stated hypothesis and success metric
- The themes the initiative was created from
- The aggregated feedback under those themes
- The features rolled into the initiative
- 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, feedback is the upstream of everything.
- REST:
GET /api/v1/golden-thread/{entity}/{id}, for dashboards and analytics. - Feedback entity reference: fields, filters, junctions.