okr

Documentation

Overview

Package okr provides types and utilities for OKR (Objectives and Key Results) goal-setting documents.

OKR is a framework popularized by Intel and Google for setting and communicating goals and results. Each Objective has associated Key Results that define how success is measured.

Key characteristics of OKRs:

• Objectives are qualitative, inspirational goals
• Key Results are quantitative, measurable outcomes
• Progress is scored 0.0-1.0, where 0.7 is typically considered success
• OKRs are typically set quarterly with annual themes

Index

• Constants
• func GenerateID() string
• func IsValid(errs []ValidationError) bool
• func ScoreDescription(score float64) string
• func ScoreGrade(score float64) string
• type Alignment
• type KeyResult
• type Metadata
• type OKRDocument
  • func New(id, name, owner string) *OKRDocument
  • func Parse(data []byte) (*OKRDocument, error)
  • func ReadFile(filepath string) (*OKRDocument, error)
  • func (doc *OKRDocument) AllKeyResults() []KeyResult
  • func (doc *OKRDocument) AllRisks() []Risk
  • func (doc *OKRDocument) CalculateOverallProgress() float64
  • func (doc *OKRDocument) JSON() ([]byte, error)
  • func (doc *OKRDocument) Validate(opts *ValidationOptions) []ValidationError
  • func (doc *OKRDocument) WriteFile(filepath string) error
• type Objective
  • func (o *Objective) CalculateProgress() float64
  • func (o *Objective) UpdateProgress()
• type Risk
• type ValidationError
  • func Errors(errs []ValidationError) []ValidationError
  • func Warnings(errs []ValidationError) []ValidationError
  • func (e ValidationError) Error() string
• type ValidationOptions
  • func DefaultValidationOptions() *ValidationOptions
  • func StrictValidationOptions() *ValidationOptions

Constants

const (
	StatusDraft     = "Draft"
	StatusActive    = "Active"
	StatusCompleted = "Completed"
	StatusCancelled = "Cancelled"
)

Status constants for OKR lifecycle.

const (
	ConfidenceLow    = "Low"    // 0-30% likely to achieve
	ConfidenceMedium = "Medium" // 30-70% likely to achieve
	ConfidenceHigh   = "High"   // 70-100% likely to achieve
)

Confidence constants for Key Result confidence levels.

const (
	ScoreExcellent = 1.0 // Fully achieved
	ScoreGood      = 0.7 // Typical success threshold
	ScoreOK        = 0.4 // Partial achievement
	ScoreFailed    = 0.0 // Not achieved
)

ScoreThresholds for OKR evaluation.

const DefaultFilename = "okr.json"

DefaultFilename is the standard OKR filename.

Functions

func GenerateID

func GenerateID() string

GenerateID generates an OKR ID based on the current date. Format: OKR-YYYY-DDD where DDD is the day of year.

func IsValid

func IsValid(errs []ValidationError) bool

IsValid returns true if there are no error-level validation issues.

func ScoreDescription

func ScoreDescription(score float64) string

ScoreDescription returns a description for a score.

func ScoreGrade

func ScoreGrade(score float64) string

ScoreGrade returns a letter grade for a score.

Types

type Alignment

type Alignment struct {
	ParentOKRID   string   `json:"parentOkrId,omitempty"`   // Parent OKR document ID
	CompanyOKRIDs []string `json:"companyOkrIds,omitempty"` // Company-level objective IDs this supports
}

Alignment represents how OKRs align with parent/company objectives.

type KeyResult

type KeyResult struct {
	ID          string  `json:"id,omitempty"`
	Title       string  `json:"title"`
	Description string  `json:"description,omitempty"`
	Owner       string  `json:"owner,omitempty"`
	Metric      string  `json:"metric,omitempty"`     // What is being measured
	Baseline    string  `json:"baseline,omitempty"`   // Starting value
	Target      string  `json:"target,omitempty"`     // Target value to achieve
	Current     string  `json:"current,omitempty"`    // Current value
	Unit        string  `json:"unit,omitempty"`       // Unit of measurement
	Score       float64 `json:"score,omitempty"`      // 0.0-1.0 achievement score
	Confidence  string  `json:"confidence,omitempty"` // Low, Medium, High
	Status      string  `json:"status,omitempty"`     // On Track, At Risk, Behind, Achieved
	DueDate     string  `json:"dueDate,omitempty"`    // ISO 8601 date
}

KeyResult represents a measurable outcome for an Objective.

type Metadata

type Metadata struct {
	ID         string    `json:"id,omitempty"`
	Name       string    `json:"name,omitempty"`
	Owner      string    `json:"owner,omitempty"`
	Team       string    `json:"team,omitempty"`
	Period     string    `json:"period,omitempty"`     // e.g., "2025-Q1", "FY2025"
	PeriodType string    `json:"periodType,omitempty"` // "quarter", "half", "annual"
	Version    string    `json:"version,omitempty"`
	Status     string    `json:"status,omitempty"`
	CreatedAt  time.Time `json:"createdAt,omitempty"`
	UpdatedAt  time.Time `json:"updatedAt,omitempty"`
}

Metadata contains document metadata.

type OKRDocument

type OKRDocument struct {
	Schema     string      `json:"$schema,omitempty"`
	Metadata   *Metadata   `json:"metadata,omitempty"`
	Theme      string      `json:"theme,omitempty"`     // Annual or quarterly theme
	Objectives []Objective `json:"objectives"`          // The OKRs
	Risks      []Risk      `json:"risks,omitempty"`     // Cross-cutting risks
	Alignment  *Alignment  `json:"alignment,omitempty"` // Links to parent/company OKRs
}

OKRDocument represents a complete OKR document containing objectives.

func New

func New(id, name, owner string) *OKRDocument

New creates a new OKR document with required fields initialized.

func Parse

func Parse(data []byte) (*OKRDocument, error)

Parse parses OKR JSON data.

func ReadFile

func ReadFile(filepath string) (*OKRDocument, error)

ReadFile reads an OKR document from a JSON file.

func (*OKRDocument) AllKeyResults

func (doc *OKRDocument) AllKeyResults() []KeyResult

AllKeyResults returns all key results from all objectives, flattened.

func (*OKRDocument) AllRisks

func (doc *OKRDocument) AllRisks() []Risk

AllRisks returns all risks (global + objective-specific), flattened.

func (*OKRDocument) CalculateOverallProgress

func (doc *OKRDocument) CalculateOverallProgress() float64

CalculateOverallProgress calculates the overall OKR document progress.

func (*OKRDocument) JSON

func (doc *OKRDocument) JSON() ([]byte, error)

JSON returns the OKR document as formatted JSON.

func (*OKRDocument) Validate

func (doc *OKRDocument) Validate(opts *ValidationOptions) []ValidationError

Validate checks the OKR document for issues.

func (*OKRDocument) WriteFile

func (doc *OKRDocument) WriteFile(filepath string) error

WriteFile writes the OKR document to a JSON file.

type Objective

type Objective struct {
	ID          string      `json:"id,omitempty"`
	Title       string      `json:"title"`
	Description string      `json:"description,omitempty"`
	Owner       string      `json:"owner,omitempty"`
	Status      string      `json:"status,omitempty"`
	KeyResults  []KeyResult `json:"keyResults"`
	Progress    float64     `json:"progress,omitempty"` // Calculated from key results (0.0-1.0)
	Risks       []Risk      `json:"risks,omitempty"`    // Objective-specific risks
	ParentID    string      `json:"parentId,omitempty"` // Link to parent/company objective
}

Objective represents an inspirational, qualitative goal.

func (*Objective) CalculateProgress

func (o *Objective) CalculateProgress() float64

CalculateProgress calculates the overall progress of an Objective based on its Key Results. Uses average scoring by default.

func (*Objective) UpdateProgress

func (o *Objective) UpdateProgress()

UpdateProgress recalculates the progress for an objective.

type Risk

type Risk struct {
	ID          string `json:"id,omitempty"`
	Title       string `json:"title"`
	Description string `json:"description,omitempty"`
	Impact      string `json:"impact,omitempty"`     // Low, Medium, High, Critical
	Likelihood  string `json:"likelihood,omitempty"` // Low, Medium, High
	Mitigation  string `json:"mitigation,omitempty"`
	Status      string `json:"status,omitempty"` // Identified, Mitigating, Resolved, Accepted
}

Risk represents a challenge or risk to achieving objectives.

type ValidationError

type ValidationError struct {
	Path    string // JSON path to the problematic field
	Message string
	IsError bool // true for errors, false for warnings
}

ValidationError represents a validation issue.

func Errors

func Errors(errs []ValidationError) []ValidationError

Errors returns only error-level validation results.

func Warnings

func Warnings(errs []ValidationError) []ValidationError

Warnings returns only warning-level validation results.

func (ValidationError) Error

func (e ValidationError) Error() string

Error implements the error interface.

type ValidationOptions

type ValidationOptions struct {
	RequireKeyResults   bool // Require at least one key result per objective
	RequireScores       bool // Require scores to be set on key results
	MinKeyResultsPerObj int  // Minimum key results per objective (default: 1)
	MaxKeyResultsPerObj int  // Maximum key results per objective (default: 5, 0 = no limit)
	MaxObjectives       int  // Maximum objectives per document (default: 5, 0 = no limit)
	RequireTargets      bool // Require target values on key results
	ValidateScoreRange  bool // Ensure scores are in 0.0-1.0 range
}

ValidationOptions configures validation behavior.

func DefaultValidationOptions

func DefaultValidationOptions() *ValidationOptions

DefaultValidationOptions returns sensible defaults.

func StrictValidationOptions

func StrictValidationOptions() *ValidationOptions

StrictValidationOptions returns strict validation settings.