OKR Management

ProBeya's OKR module connects strategic intent to execution. Objectives and Key Results (OKRs) are managed in a tree structure where objectives define qualitative goals and key results provide quantitative measures of success. Progress auto-computes from key result values, confidence scores reflect time-based trajectory, and a strategic alignment matrix visualizes coverage gaps.

This module is part of ProBeya's Portfolio (PPM) capability, designed for PMO teams, OpEx coordinators, and transformation leaders who need to ensure that projects and programs deliver on strategic commitments.

Overview

Organizations invest in transformation programs and project portfolios, but often lose sight of whether those investments are driving strategic outcomes. OKRs bridge this gap by creating an explicit link between "what we are doing" (projects, programs) and "what we want to achieve" (strategic objectives).

ProBeya's OKR module solves three specific problems:

1. Visibility -- The OKR tree view shows all objectives and key results for a period at a glance, with real-time progress and confidence indicators.
2. Accountability -- Each OKR has an owner, and progress is computed from measurable data rather than subjective status updates.
3. Alignment -- The strategic alignment matrix reveals which strategic objectives are well-supported by OKRs and which have coverage gaps.

Getting Started

1. Navigate to a workspace and select Portfolio > OKRs from the sidebar.
2. The dashboard opens with a period selector defaulting to the current quarter.
3. Click Add OKR to create a new objective or key result.
4. For objectives: provide a title, description, period, owner, and optionally link to a strategic objective.
5. For key results: provide a title, target value, unit of measure, and assign it to a parent objective.
6. Link projects or programs to key results to auto-compute progress from project completion.
7. Use the Strategic Alignment Matrix at the bottom of the dashboard to verify strategic coverage.

Key Concepts

Term	Definition
Objective	A qualitative, aspirational goal that describes what the organization wants to achieve.
Key Result	A quantitative measure with a target value that tracks progress toward an objective.
Period	The time frame for the OKR cycle, typically a quarter (e.g., "2026-Q2").
Current Value	The present measurement of a key result toward its target.
Target Value	The goal value that constitutes 100% achievement of a key result.
Confidence	An auto-computed score (0-100) reflecting whether the OKR is on track given elapsed time.
Status	on_track, at_risk, behind, or achieved -- reflects the overall health of the OKR.
Strategic Objective	An organization-level strategic goal that OKR objectives can align to.
Contribution Weight	When linking a project to an OKR, the weight determines how much that project's completion contributes to the key result progress.

How It Works

OKR Tree Structure

OKRs form a two-level hierarchy:

Objective: "Improve manufacturing yield"
  ├── Key Result: "Reduce scrap rate from 8% to 3%"
  ├── Key Result: "Increase first-pass yield to 95%"
  └── Key Result: "Eliminate top 3 defect types"

The tree view on the dashboard renders this hierarchy with progress bars, confidence indicators, and linked project counts for each node.

Progress Computation

Progress is computed differently for objectives and key results:

• Key Results: progress = currentValue / targetValue x 100. If the target is 100 units and the current value is 75, progress is 75%.
• Objectives: progress = average(child key result progresses). An objective with three key results at 80%, 60%, and 40% shows 60% progress.

All progress calculations use pure helper functions (computeKeyResultProgress, computeObjectiveProgress) in a dedicated okr-progress.ts library, keeping business logic separate from data access.

Confidence Scoring

Confidence reflects whether the OKR is on track given elapsed time. The computeConfidence function compares actual progress against expected progress based on the period's start and end dates.

For example, if a quarter is 50% elapsed and a key result is at 50% progress, confidence is high. If the same key result is only at 20% progress at the midpoint, confidence drops accordingly.

When a key result's confidence is updated, the system automatically bubbles the recomputation up to the parent objective.

Project and Program Linking

Key results can be linked to projects and programs via ppmOkrProjectLinks. Each link carries a contribution weight that determines how much the project's completion percentage influences the key result's current value.

The recalculateProgress procedure:

1. Fetches all linked projects and their completion percentages
2. Computes a weighted current value using the computeOkrValueFromProjectCompletion helper
3. Persists the updated current value
4. Recomputes confidence and bubbles up to the parent objective

This creates a live connection between project execution and strategic outcome measurement.

Strategic Alignment Matrix

The getStrategicAlignment endpoint returns a matrix of OKR objectives versus strategic objectives. Each cell indicates:

• isAligned -- Whether the OKR is linked to that strategic objective
• Strength -- The OKR's confidence score when aligned (0 when not aligned)

This powers a heatmap visualization that reveals:

• Which strategic objectives have strong OKR coverage (green cells)
• Which strategic objectives are under-supported (empty columns)
• Which OKRs are performing well or poorly against their strategic intent

Configuration

Setting	Description
Period Format	Quarters are formatted as "YYYY-QN" (e.g., "2026-Q2"). Custom periods are also supported.
Units	Key results support any unit of measure (%, count, currency, hours, etc.).
Tags	Optional tag array for categorizing OKRs (e.g., "Quality," "Growth," "Compliance").
Strategic Objectives	Organization-level goals defined in the PPM strategic objectives table. OKR objectives link to these for alignment tracking.

Permissions

Role	Capabilities
Portfolio Viewer	View OKR tree, alignment matrix, and individual OKR details
OKR Owner	Update owned key results (current value, status)
Portfolio Manager	Create, update, delete OKRs; link/unlink projects; recalculate progress
Organization Admin	Full access including strategic objective management

All operations enforce multi-tenant isolation. Key results validate parent objective ownership, and project links verify both the OKR and the linked project belong to the same organization.

Tips & Best Practices

Limit objectives to 3-5 per period

Each objective should have 2-5 key results. More than 5 objectives per quarter creates tracking overhead and dilutes focus.

Make key results measurable, not binary

"Launch new product line" is a task, not a key result. "Generate $500K revenue from new product line" is measurable and trackable over time.

Link projects to key results, not objectives

Project linking is most meaningful at the key result level, where completion percentages can directly influence a quantitative target.

Review the alignment matrix monthly

The strategic alignment matrix quickly reveals coverage gaps. If a strategic objective has no aligned OKRs, either the strategy needs revision or new OKRs should be created.

Troubleshooting

Issue	Resolution
Confidence not updating	Run the recalculate progress action for the OKR. Confidence is recomputed from current values and period dates.
Cannot create key result	Key results require a parent objective. Ensure the parent exists and is of type "objective" (not another key result).
Project link not affecting progress	Verify the link has a non-zero contribution weight. Run recalculate progress to pull the latest project completion data.
Alignment matrix empty	The matrix requires both strategic objectives and OKR objectives to exist for the selected period. Verify both are configured.

Related Features

• PPM Projects -- Projects linked to OKRs provide the execution data that drives key result progress.
• Governance Framework -- Governance processes ensure OKRs are reviewed and updated on schedule.
• KPI Boards -- Operational KPIs can serve as data sources for key result measurements.
• Dependencies -- Project dependencies may impact the timeline for achieving key results.
• Kaizen / Problem Solving -- When a key result falls behind, initiate a Kaizen project to investigate and recover.