# OKRs

> Objectives and Key Results, quarterly targets that operationalize the vision and close the loop via outcome_id.

Source: https://productos.ca/documentation/pages/strategy/okrs (last reviewed 2026-09-23)

The OKRs page tracks Objectives and their measurable Key Results, each objective tagged with a time frame (usually a quarter).

## What you'll see

- **Table**: one row per objective: title, Time Frame (free text, e.g. "Q1 2026"), Status (`active | completed | cancelled`), Owner, KR count, and Progress (average completion across its key results, computed from baseline → target → current)
- **OKR overview strip**: counts of at-risk (under 30% progress), on-track, achieved (completed, or 80%+) and cancelled objectives
- **Filter bar**: status

## Row drawer (objective)

- Title, description, status, time frame, owner
- **Initiatives**: link the initiatives that serve this objective. The list is stored as `initiative_ids` on the objective, so the same links are readable and writable through the API and the MCP connector (see below). An initiative that has been moved to the trash drops off the list the next time the drawer opens.
- KR list with inline editing
- **Add KR** button

## Key results

Key results are edited inside their objective's drawer rather than in a drawer of their own:

- Title, metric name, unit, baseline, target, current
- Status pill (`on-track | at-risk | behind | completed`), set by hand
- **Linked outcome**: `outcome_id` closes the OKR-to-outcome loop, but it's settable through the API only; the drawer has no outcome picker

## Common actions

- **Add Objective** button in the toolbar
- Edit any KR's `current` value inline in the objective's drawer
- **ProductSense** in the toolbar: AI reviews your objectives and proposes edits

## How OKRs and outcomes interact

A KR's `outcome_id` ties it to a recorded Outcome, so the Golden Thread's end (outcomes) can be traced back to strategic measurement. Nothing flips automatically: when the outcome's result lands on `hit`, mark the KR `completed` yourself.

## Linking initiatives through the API and MCP

`initiative_ids` is a writable field on `POST /api/v1/objectives` and `PATCH /api/v1/objectives/{id}`, and on the `create_objectives`, `update_objectives` and `update_entities` catalog actions over MCP. It takes an array of initiative ids (uuids).

- Every id must be a live initiative in your workspace. A write that names an unknown initiative, a trashed one, or one from another workspace is refused with a `422` that lists the offending ids, and nothing is saved.
- Duplicates are dropped and `[]` clears the list. `null` clears it too.
- `describe_entity` lists the field with type `uuid[]` and `references: "initiatives"`, so a connector knows which type to search for the ids.
- A dry run of `update_objectives` or `update_entities` names the current and the proposed initiatives under `refs` on the change, the way `get_entity` names single-id fields, so the diff reads as titles rather than ids.
- The export workbook carries the same links as a `Linked Initiatives` column on the Objectives tab (initiative titles, semicolon-separated), which re-imports by title.

## Related

- [Objectives API reference](https://productos.ca/documentation/api/v1/reference/objectives)
- [Key Results API reference](https://productos.ca/documentation/api/v1/reference/key-results)
- [Outcomes page](https://productos.ca/documentation/pages/golden-thread/outcomes)