Goals & OKRs

A goal is the outcome a team is trying to ship. Key results are how the team knows it is shipping. Most teams agree on a small set of these every quarter, write them down, and then lose track of them by week four because the goal lives in one tool and the work lives in another. Disco Parrot keeps them in the same place. A key result on a goal can point at the initiative that moves it, and the progress on the key result updates as the initiative ships. The team reads the goal and the work side by side, and the goal does not drift.

This works for both shapes of outcome-tracking a team usually wants. A project-level goal belongs to a single project and tracks an outcome that team owns end to end: Improve customer-reported export usability for the Analytics team, with a key result pointing at the CSV Export initiative. A workspace-level goal belongs to nobody specific and tracks an outcome leadership cares about across the company: Ship five customer-facing launches in Q4, with key results pointing at the initiatives the leadership team is watching across multiple portfolios. Both shapes live as real records, both shapes show up where they should, and the platform never asks you to maintain a separate dashboard to read either of them.

If you are coming from a dedicated OKR tool, this is closer to a Workboard or Lattice rollup than to a spreadsheet, with the important difference that the key results are not numbers you maintain by hand. They derive from the real work. If you are coming from Jira or Linear, this is a piece those tools do not really cover; goals tend to live in a separate document the team forgets about. Putting them next to the work is the point.

How a goal sits in the work model

A goal can belong to a project or live workspace-wide. It carries one or more key results, each of which links to one or more initiatives (driving auto-progress) or to a portfolio (a supporting link, no progress contribution). The links are typed and tracked separately so the platform can do the right math.

How it looks in practice

Continuing the worked example.

Sarah Chen and the Analytics team are running two goals this quarter. The first is a team-level goal sitting on the Insights project; the second is a workspace-level goal owned by Marcus Reed, the VP of Product.

Sarah's project-level goal.

The goal carries one key result.

The KR links to the CSV Export on the Reporting Page initiative with a contribution weight of 1 (the full progress of the initiative drives the KR). As the initiative's plans ship, the platform recomputes the KR's current value. With the CSV server endpoint plan now Complete (one of three plans done), the KR sits at 33%.

Marcus's workspace-level goal.

It carries two key results.

Now look at how the goals connect.

Upward. Sarah's goal belongs to the Insights project; it appears on the project's Goals tab. Marcus's goal has no project; it appears in the workspace goals section on the Planning home dashboard. Both are visible to every member of the workspace with goals.read scope, regardless of project membership.

Downward. Sarah's KR links to one initiative; the initiative's plans-progress rollup drives the KR's current value, recomputed automatically as plans ship. Marcus's KRs do not link to initiatives at all; the first is a manual counter he updates as launches close, and the second is a supporting link to a portfolio that does not contribute to auto-progress (portfolio links are descriptive only).

Sideways. The Q4 Launches portfolio's Overview tab will surface Marcus's goal as a Connected goal chip, because one of the KRs links to it. The link is one-way; the goal references the portfolio, the portfolio reads the link back. No new access is granted in either direction.

Rollups at a glance. Sarah opens her goal and sees: 1 KR, 33% progress, On Track status. Marcus opens his and sees: 2 KRs, the launches-completed counter at 1 of 5, and a status chip he sets manually. Both goals show their status chip in the workspace goals dashboard.

When you create one

The flow is short.

1. Open the right surface. For a project-level goal, click into the project, open the Goals tab, click New Goal. For a workspace-level goal, open the Planning home dashboard and click New Goal in the workspace goals section there.
2. Pick the time period. A goal needs a time window. Pick a period type (quarter / half / annual / custom), type the start and end dates, and add an optional period label (Q2 2026 is the convention). The fields are independent; the period type is a label the platform records alongside the dates so a quarterly goal reads cleanly later.
3. Enter the title and the owner. Title is required and short. Owner defaults to you and is freeform; pick whoever is accountable for the outcome.
4. Save. The goal lands at status On Track. From here you add key results.

The owner field is freeform on purpose. A goal's owner is a label the team adopts, not a userId reference. This means you can list the team as the owner (Analytics team) on a goal nobody on the team wants to be individually accountable for, or list an external sponsor (Customer Success leadership) on a goal driven from outside the engineering org. The team picks the convention.

Goal statuses

Five values, set on the goal and on each individual key result.

Status is a team signal, not a state machine

Unlike initiatives, plans, and bugs, the goal workflow is intentionally flat. The platform does not enforce transitions; any status can move to any other status at any time. The reason is that goal status is a signal the team raises to communicate the state of the outcome, not a state machine the platform should adjudicate. A leader who decides the goal is At Risk on a Tuesday wants to flip it in one click, not negotiate a transition table.

A KR carries its own status alongside the goal. Each KR can sit at On Track while the goal sits at At Risk (or vice versa) when the team wants to communicate that the overall outcome is at risk even though the individual metrics are still moving. The team picks the convention; the platform does not force them to agree.

Goals are not snapshot-versioned

A goal does not have a version history tab the way an initiative or a plan does. The shape of a goal is a fast-cycling outcome record with a small field set and a short lifecycle (one quarter, usually); snapshotting the whole record on every save would create noise without value. The per-event audit log is the source of truth for what changed.

Goal status flips, title edits, time-period changes, link adds and removes, and goal lifecycle events (create / delete / restore) all write audit entries with the actor and the timestamp. KR currentValue updates write an audit entry as well, with the before-and-after values. The audit trail is the right grain for a quarterly cadence: a leader reading the goal at quarter-end can see exactly when At Risk was first raised, who raised it, and how soon the team flipped it back (or did not). The contrast with initiatives and plans is intentional; those are long-lived spec records where the version snapshots earn their keep, and the platform draws the line where the shape changes.

Soft-delete and restore

A goal can be soft-deleted from the inline Delete action on the row. Soft-deleted goals drop out of the default Goals lists; they remain in the platform's record. The platform's restore endpoint (POST /goals/:goalId/restore) returns a goal to the active list at its previous status with KRs and links intact; the restore is recorded in the audit log with the actor and the timestamp.

Key results

A key result is the measurable signal the goal is moving. Disco Parrot supports four metric types, two progress modes, and two link types so the team can shape the KR to the actual signal rather than forcing every outcome into a percentage.

Metric types

The KR editor offers four shapes. The picker defaults to Number, but most teams flip it to Percentage or Currency depending on what the KR is actually measuring.

A few constraints worth knowing. Boolean KRs always carry initial value 0 and target value 1; the editor locks the fields and the server rejects any other combination. Numeric KRs (Percentage, Number, Currency) require the initial and target values to differ, so the math has somewhere to go; the platform rejects a target value equal to the initial value with a clear error. Currency KRs render in the workspace's primary currency setting on the goal card; the platform does not convert.

The metric type is set when the KR is created. Changing it later requires the team to re-enter the initial, target, and current values, since the units do not translate cleanly across types.

Manual mode and auto mode

The progress mode decides who moves the KR's current value.

• Manual mode means a person updates the current value when something changes. Useful for KRs that do not have a clean derivation (a counter the leader tracks, a metric that lives in a BI tool the platform does not read). Marcus's Q4 launches completed KR is manual; he updates it weekly as launches close.
• Auto mode means the platform computes the current value from the linked initiatives. Useful for KRs that can be derived from real work. Sarah's CSV export adoption KR is auto; the platform recomputes it whenever the linked initiative's plans-progress rollup changes.

Auto mode is the lever that makes goals feel alive. A team that uses auto mode on every KR where they can finds the dashboard updates itself; the goal review at the end of the quarter is reading a number the team has been watching the whole time, not catching up on a number nobody touched. A team that uses manual mode on every KR is essentially keeping a spreadsheet. Pick auto whenever the work can drive the number.

Two link types

A KR can link to one or more initiatives, or to a portfolio. The link type decides whether the link drives auto-progress.

• Initiative-targeted links drive auto-progress. The KR aggregates the progress of every linked initiative, weighted by the contribution value the KR specifies for each link (default 1, meaning equal weight). When any linked initiative moves status or progress, the KR recomputes.
• Portfolio-supporting links are descriptive only. They show up as a Connected goal chip on the portfolio's Overview tab, and they let a reader navigate from the goal to the portfolio and back. They do not contribute to the KR's current value; manual mode is the right pairing.

The two link types live on the same KR. A KR can have three initiative-targeted links (driving auto-progress as a weighted average) and one portfolio-supporting link (descriptive only) at the same time.

The auto-progress math

For a numeric KR in auto mode, the formula is straightforward. The platform takes each linked initiative's progress percentage, multiplies it by the link's contribution weight, sums across all initiative-targeted links, and divides by the total weight. That weighted average becomes the progress fraction; the KR's current value is initialValue + progressFraction × (targetValue − initialValue), rounded to two decimals. See Rollups for the full subsystem treatment, including the write-through semantics and the boolean-vs-numeric mode trade-off.

For a boolean KR in auto mode, the math is even simpler: the current value flips to 1 if every linked initiative is Done, and stays at 0 otherwise. A boolean KR linked to three initiatives reads 100% only when all three are done; until then it reads 0%.

Portfolio-supporting links are filtered out of the computation before the math runs, so they do not contribute even if you forgot to pair them with manual mode. A KR with only portfolio-supporting links (no initiative-targeted links) recomputes to 0 in auto mode, which is the platform's honest signal that no work is driving the number; flip the KR to manual mode in that case.

The recompute is event-driven, not polled. The platform listens for an initiative.updated event with a status change OR a progress change; a title edit, an owner change, or a body edit on an initiative does not recompute the linked KRs. This is deliberate so that editorial changes on initiatives do not move the team's goal dashboard around.

Connecting key results to the work

The link from a key result to an initiative is the lever that turns a KR from a number someone maintains into a number the work derives. The flow itself is fast; the choices you make at link time decide how trustworthy the auto-progress reads later.

Linking from the KR

From the project Goals tab, expand the goal, expand the KR, click Link to Initiative. The picker dialog opens with a segmented control at the top to choose the target type (Initiative or Portfolio) and a search box to find the specific record. Pick the type, search, click the target, save. The KR's current value recomputes immediately if the KR is in auto mode and the target is an initiative.

Each KR can carry several links. Sarah's CSV export adoption KR could later add a second link to a follow-up initiative (say, Export to Google Sheets) without touching the first link; the platform would aggregate progress across both. The picker is what teams use mid-quarter as the work splits or evolves.

How the weighting works

Each initiative-targeted link carries a contribution value the platform uses as a weight in the KR's weighted average. The dialog today saves every link at the same weight; a KR with three initiative-targeted links averages the progress of those initiatives evenly. The API supports unequal contribution values (a heavyweight initiative driving more of the KR than the others); the SPA picks the equal-weight default and the per-link control is a future affordance.

For now, the practical guidance is straightforward. If two initiatives both drive the same outcome equally, link them both and let the math average them. If one initiative is the lead and the others are supporting work, link only the lead as the initiative-targeted link and add the others as portfolio-supporting links (which do not contribute to auto-progress); the KR reads as a single-driver number, which is honest about what the team is actually tracking.

When auto-progress is not the right answer

Auto mode is the right default for any KR the platform can derive. The fact that the team should know is the boundary: there are real, important KRs that the platform cannot drive, and the product is better for letting them stay manual instead of pretending it can derive them.

Revenue KRs live in the team's billing system; net-new-customer KRs live in the CRM; NPS KRs live in the survey tool; customer-health KRs live in the customer-success platform. None of these are work the platform owns, and the platform does not pretend otherwise. A KR pointed at one of these signals stays in manual mode and the owner updates it on a cadence (a weekly Friday update is the convention most teams settle into).

The manual cadence is what makes the manual KRs trustworthy at quarter-end. A number updated weekly, with the audit log showing the cadence held, is a credible read on the outcome. A number updated once at the start of the quarter and once at the end is a guess dressed up as data. The platform does not enforce the cadence; the team's own discipline does. Pairing the discipline with the platform's audit trail is what turns manual KRs into a real record rather than a self-report.

Common OKR shapes

Pick the shape that matches the conversation your team is trying to have. Most teams settle on one of these four within a quarter or two of using OKRs and rarely change it after.

The single-outcome project goal. One goal, two to four KRs, every KR linked to one or two initiatives that drive it. Sarah's Improve customer-reported export usability is this shape. The team reads the goal as a single story arc across the quarter; the auto-progress on the KRs tells them whether the work is landing.

The cross-team workspace goal aligned to a portfolio. One workspace-scoped goal, KRs that mix manual mode (a launch counter the leader maintains) and portfolio-supporting links (the relevant portfolios surface the goal as Connected). Marcus's Ship five customer-facing launches in Q4 is this shape. The portfolio link is the architectural cue that the leader is reading rollups, not driving the work.

The annual goal with quarterly KR resets. Time period set to the year, KRs swapped each quarter as the team re-cuts the work. The platform handles this with KR creation, archival, and the time period field on the goal; the audit log preserves the full year as one record so a year-end review can read the whole arc.

The team OKR that ladders to a company OKR. Two goals, one at the team level and one at the company level. The team's KR and the company's KR both link to the same initiative. The platform does not enforce the ladder; the shared link is what makes the ladder readable. A team using this shape gets honest contribution at company-level reviews because the linkage is real, not narrated.

Why auto mode is the lever

Auto mode is the single most distinctive thing about goals in Disco Parrot, and the reason worth explaining is the contrast with how OKR-tracking usually works.

In a typical setup, a team picks an OKR tool that lives separately from the work-tracker. The KRs in the tool are numbers maintained by hand on a weekly cadence. Someone on the team remembers to update the spreadsheet on Thursday afternoon before the Friday review; someone forgets to update it the next week; by week four the dashboard reads numbers nobody trusts, and the leadership review reads off a doc nobody opened all month. The OKR exercise becomes the calendar event, not the management instrument.

Auto mode breaks the cadence. A KR linked to an initiative recomputes whenever the initiative's progress moves; the team reads the KR's current value as a side effect of shipping the work. The Friday review reads off a number that has been moving all week, in real time, from the audit log of the work itself. The reading is grounded in what shipped, not in someone's interpretation of what shipped.

The contrast with dedicated OKR tools is that the integration was the point of the product, and the integration is automatic. The contrast with spreadsheets is structural: a spreadsheet cannot derive a number; a row connected to a record can. The lever is not the auto-progress math (the math is simple); the lever is the link from the KR to the initiative, which is what the team writes once and the platform reads forever.

When to use a project goal vs a workspace goal

The choice between project-scoped and workspace-scoped is mostly about who owns the outcome.

A project-scoped goal sits on a single project and belongs to the team that owns the project. The team manages it from the project's Goals tab; the goal appears in the workspace goals dashboard alongside other goals, but it lives where the work lives. Use this when the goal is something the team can ship inside its own scope.

A workspace-scoped goal belongs to nobody specific and lives in the workspace goals area. Use this when the goal cuts across teams (a launch involving Analytics, Onboarding, and Billing), when leadership owns the goal directly, or when the goal does not map cleanly to a single project's work. The KRs can still link to project-level initiatives, so a workspace goal is not isolated from the work; it is just not parented under one project.

You can change a goal's scope later (set or clear the project) without losing the KRs or the links, so an experiment that starts as a project goal and grows into a workspace goal can be lifted without re-creating the goal record.

How a goal moves through a quarter

The shape of work on a goal is not a checklist; it is a rhythm. The same record passes through four distinct beats over the quarter, and each beat is read by a different audience.

At kickoff. The team writes the goal at the start of the quarter. The title, the owner, and the time period land first. Then the KRs go in (two to four; more than five and the team stops reading them, fewer than two and the goal is probably one KR pretending to be two). Each KR gets a metric type, a target value, and a progress mode. The team links each auto-mode KR to the initiatives that drive it, picks contribution weights if any link is unequal, and adds portfolio-supporting links to whichever portfolios should surface the goal. Status defaults to On Track. The kickoff is the moment the team commits to the outcome on the record; the audit log carries the commitment forward.

Through steady state. Most weeks the goal does not need a touch. Auto-mode KRs are recomputing on their own as initiatives ship; manual-mode KRs get their weekly Friday update from the owner. The team's read on the goal is a quick glance at the Goals tab during their weekly planning, mainly to see if any status chip has flipped. The leader's read on the goal is a quick glance at the Planning home dashboard during their monthly cross-team review, mainly to see if any At Risk or Off Track chips have appeared.

At the mid-quarter signal. Sometime in week six or seven, every quarter, a goal usually starts to slip. The auto-progress KRs are not where they should be by now; a manual KR has not moved for three weeks. The owner is the one who has to flip the status to At Risk or Off Track honestly. This is the moment that distinguishes a team that uses OKRs as a real instrument from a team that uses them as a presentation. The team flips the status, writes a one-paragraph note in the description explaining what they are doing about it, and the conversation shifts from are we on track? to what changes?

At the close. The window ends. Achieved goals get marked Achieved; goals that landed but did not hit the target stay where they are with a note explaining the shortfall; goals that the team decided to drop mid-quarter get Cancelled with a note explaining why. The team's quarterly retrospective reads off the goal record: KR final values, the audit log showing when status flipped, the linked initiatives the team can navigate back to. A goal that sat at On Track all quarter and ended at Achieved is suspect; either the team was lucky or the team was not watching. A team that used the status chip honestly all quarter has a quarter-end story that an outside reader can actually trust.

Reading a goal at quarter-end

The quarter-end read is the moment OKRs either pay off or expose themselves as a calendar event. A goal in Disco Parrot carries four artefacts a leader can read in order at the end of the quarter.

The KR final values. The literal outcome. CSV export adoption at 100%; Q4 launches completed at 4 of 5. The platform stops the clock when the time period ends; the values stay readable on the goal card forever.

The per-event audit log. Every status flip with the actor and the date, every KR currentValue update, every link added or removed. A goal that read On Track for ten weeks and Achieved on the last Friday with a single status flip looks different from a goal that flipped to At Risk in week six, stayed there through week ten, and recovered to Achieved with a real trajectory. The audit log makes the difference visible without anyone narrating it.

The linked initiatives. Click through to each one. The initiative's own progress, version history, and shipped plans are the work that drove the KR. A KR at 60% with a linked initiative at Done is a sign the initiative did not actually drive the outcome; a KR at 100% with three linked initiatives all Done reads as a clean delivery. The link is a real trail.

The description-field notes. The team's own read on what happened, written by the team. Healthy teams keep a running set of notes in the goal's description field through the quarter: the initial scope underestimated the timezone work, added two plans in week six, on track for the revised scope. At quarter-end the notes read as the team's honest story, not as leadership's interpretation of a status field.

A goal carrying all four of these reads as a real outcome, not a number set at the start and a different number set at the end. The platform's job is to keep the four readable side by side without anyone assembling them by hand.

Starting OKRs in this workspace

A team rolling out OKRs for the first time does not need to make every choice on day one. The minimum viable setup is a single workspace-level goal with two KRs, written by whoever is championing the rollout.

Save the goal, link one KR to an initiative the team is already running, and the dashboard starts updating itself the same afternoon. The first quarter of OKR adoption is the moment most teams pick shapes that do not survive contact with the work; starting with one goal and watching it move is the cheapest way to learn what the team actually needs from the OKR shape.

Workspace owners often ask whether to seed every project with a project-level goal at rollout. The honest answer is not yet. Project teams that have not asked for goals do not need them imposed; the platform's design treats goals as opt-in per project, and a project's Goals tab sits empty until the team writes one. The right rollout sequence is workspace-level goals first (leadership owns the cadence), project-level goals as teams ask for them. Six quarters in, most projects carry one or two goals each; the trajectory is bottom-up adoption, not a top-down audit.

The cadence to settle into the first quarter: one workspace-level kickoff goal, weekly status check by the owner, mid-quarter signal flip if the work slips, quarter-end retrospective using the four artefacts above. After one quarter the team knows whether OKRs are working for them. After two quarters they know which projects benefit from project-level goals. By quarter four the rollout is naturalized; the team writes goals because the goals are useful, not because someone told them to.

Where you read goals

Goals show up in three places.

The project Goals tab

Every project has a Goals tab on its detail page. The tab lists the project's goals as an accordion; expanding a row shows the goal's KRs with their current values, progress bars, and link targets. The team manages the project's goals from here: create, edit, delete, restore. KR current values for manual-mode KRs are inline-editable in the row.

The accordion is the canonical project-level surface. Most of the day-to-day work on a project's goals happens here.

The workspace goals section on the Planning home

The Planning home dashboard at /planning carries a workspace goals section that lists every workspace-scoped goal (goals without a project parent). Each goal renders as a card with the title, status, time period, and the KR list with current values. The cards are read-only; clicking through opens the editor drawer.

This is the leadership view. A VP scanning the workspace for which company-wide goals are At Risk lands here, not on a specific project's Goals tab. Project-scoped goals do not appear in the workspace section by design; they live on their project's Goals tab where the team that owns them works.

Restoring a soft-deleted goal

A goal soft-deleted from its inline Delete action drops out of default lists. To bring it back, the platform's restore endpoint (POST /goals/:goalId/restore) returns the goal at its previous status with KRs and links intact. The endpoint is the path for now; the audit log records both the soft-delete and the restore with the actor and timestamp on each.

The portfolio Connected goals strip

A portfolio's Overview tab carries a Connected goals strip showing every goal that has at least one KR linked to the portfolio (via a portfolio-supporting link, which is the only kind a KR can have on a portfolio target). The chips are click-throughs to the goals; access to the underlying goal is governed by goals.read scope, not by portfolio membership.

This is the cross-team rollup view. A leader running a portfolio sees which goals are pointed at it without leaving the portfolio.

Permissions

Two scopes govern goals.

• goals.read lets a person list and view goals, KRs, and links. Most workspace members have this by default; goals are not access-gated by project membership.
• goals.manage lets a person create, edit, delete, restore, and link goals and KRs. This is the elevated scope.

Both scopes are workspace-wide. There is no per-project or per-portfolio variant; if you have goals.manage, you can edit any goal in the workspace. This is deliberate: the platform's privacy model treats goals as transparent by default, the same way it treats workflows and audit trails. Outcome-tracking that requires a hidden access model rarely survives the team-membership churn of a long-running quarter.

Cross-links