From cfd3c7cd1c90a4714ce2c8e94792c033f1f26353 Mon Sep 17 00:00:00 2001 From: Kjell Tore Guttormsen Date: Wed, 8 Apr 2026 15:29:48 +0200 Subject: [PATCH] =?UTF-8?q?docs(okr):=20rewrite=20README=20v2=20=E2=80=94?= =?UTF-8?q?=20onboarding-first,=20show=20real=20value?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Major restructure based on user feedback: - Lead with onboarding as the key differentiator - Add "Bring What You Have" section with two real examples: tildelingsbrev parsing and existing OKR quality review - Show iterative development process, not one-shot usage - Stronger value proposition: OKR expert that learns your context - Remove simplistic Q&A example that made plugin look like a form-filler Co-Authored-By: Claude Opus 4.6 --- plugins/okr/README.md | 161 ++++++++++++++++++++++++++---------------- 1 file changed, 102 insertions(+), 59 deletions(-) diff --git a/plugins/okr/README.md b/plugins/okr/README.md index 719e909..46ccc08 100644 --- a/plugins/okr/README.md +++ b/plugins/okr/README.md @@ -6,57 +6,104 @@ ## The Problem -OKR sounds simple until you try it in public sector. Your organization gets a tildelingsbrev with 47 requirements, and someone asks you to turn it into "3-5 inspiring Objectives." Teams write KRs that are just task lists. Tertial cycles don't match the quarterly model from Google. And when Riksrevisjonen asks for documentation, nobody can trace which OKR delivered which mandate requirement. +OKR sounds simple until you try it in public sector. Your tildelingsbrev has 47 requirements and someone asks you to turn it into "3-5 inspiring Objectives." Teams write Key Results that are just task lists. Tertial cycles don't match the quarterly model from Google. And when Riksrevisjonen asks for documentation, nobody can trace which OKR delivered which mandate requirement. -Most OKR tools assume you're a startup with quarterly goals and stock options. You're not. You have political steering, budget cycles tied to Stortinget, and mid-cycle priority changes from a minister who read something in Aftenposten. +Most OKR resources assume you're a startup. You're not. You have political steering, budget cycles tied to Stortinget, and mid-cycle priority changes from a minister who read something in Aftenposten. -This plugin understands that context. +**This plugin gives you an OKR expert that knows Norwegian public sector governance, learns your organization's context, and works alongside you through the entire OKR process** — from translating your tildelingsbrev into OKR candidates, through iterative quality improvement, to check-in meetings and cycle reviews. -## What You Get +## How It Works: Onboarding First -- **Guided OKR writing** that turns vague ambitions into outcome-focused Objectives with measurable Key Results — including baseline, target, and data source -- **Quality scoring** against a rubric that catches the 19 most common OKR mistakes (activity masquerading as outcome, sandbagging, missing baselines, too many KRs) -- **Tildelingsbrev translation** that separates what's actually an OKR candidate from what's a KPI, a compliance requirement, or a reporting routine -- **Cascade visualization** from organization strategy down to team OKR, with alignment gap detection -- **Meeting materials** for check-ins, reviews, workshops, and 1:1 conversations using the CFR framework +The plugin starts by learning your context. This is the most important step — it's what transforms generic OKR advice into guidance that fits your organization. -## See It In Action +`/okr:oppsett` runs an interactive interview that captures: + +- **Your organization** — which agency, which sector, which ministry +- **Your OKR maturity** — first attempt, pilot phase, or scaling across teams +- **Your cycle** — tertial or quarterly, current phase, team count +- **Your strategic documents** — tildelingsbrev goals, virksomhetsplan priorities +- **Your tools** — Linear integration, meeting tools, delivery methodology + +This context is saved locally and automatically injected into every conversation. You do it once. After that, the plugin knows who you are, what cycle you're in, and what your strategic goals are. + +## Bring What You Have + +You don't need to start from scratch. The plugin meets you where you are: + +**Have a tildelingsbrev?** The plugin parses it, separates what's actually an OKR candidate from what's a KPI, a compliance requirement, or a reporting routine — and drafts aligned OKR directly: ``` -> /okr:skriv We want to improve our digital services for driver's license renewals +> /okr:governance -Which team is this for, and what cycle? -> Digital avdeling, T2-2026 +I see from your tildelingsbrev that Samferdselsdepartementet expects: +- Reduce traffic fatalities by 50% by 2030 (vs. 2020) → OKR candidate +- Maintain 98% tunnel availability → KPI, not OKR +- Report quarterly on maintenance spend → Reporting routine -What's the current state — do you have baseline numbers? -> About 45% do it digitally. Average processing takes 14 business days. -> User satisfaction is 3.4 out of 5. +Here are 2 OKR candidates derived from the mandate: -─────────────────────────────────────────────────── +Objective: Drive measurable progress toward Vision Zero on Norwegian roads -OKR for Digital avdeling — T2-2026 + KR1: Reduce fatalities from 95 (2025) to 85 (2026) + Source: SSB table 08463 | Type: Committed + KR2: Reduce severe injuries from 650 to 600 + Source: SSB | Type: Committed + KR3: Complete safety interventions on 100% of high-risk road segments + Source: Internal action plan | Type: Aspirational -Objective: Make driver's license renewal a frictionless experience - -Key Results: -1. Increase fully digital renewals from 45% to 75% - Measurement: Monthly report from case system - Type: Aspirational (target score: 0.7) - -2. Reduce average processing time from 14 to 5 business days - Measurement: Case management system - Type: Committed (target score: 1.0) - -3. Achieve user satisfaction of 4.2/5.0 (baseline: 3.4) - Measurement: Citizen survey, quarterly - Type: Aspirational (target score: 0.7) - -─────────────────────────────────────────────────── - -Shall I run a quality check on this? (/okr:kvalitet) -Or cascade it from an organization-level objective? (/okr:kaskade) +Shall I quality-check these? Or cascade them to team level? ``` +**Have existing OKR that need improvement?** Paste them in and get scored feedback with specific rewrites: + +``` +> /okr:kvalitet + +Our current OKR: +Objective: Improve customer service +KR1: Complete 5 customer service training courses +KR2: Answer 90% of calls within 3 minutes + +─── Quality Assessment ─── + +Objective: "Improve customer service" — Score: 4/10 + ✗ Vague — what does "improve" mean? + ✗ Not inspiring — reads like a task, not a goal + → Suggested rewrite: "Become the most responsive service unit in the agency" + +KR1: "Complete 5 training courses" — Score: 2/10 + ✗ Activity, not outcome — measures what you do, not what changes + ✗ No connection to customer experience + → Suggested rewrite: "Increase citizen satisfaction from 3.2 to 4.5/5.0" + +KR2: "Answer 90% of calls within 3 minutes" — Score: 6/10 + ✓ Measurable with clear target + ✗ Missing baseline — what's the current level? + → Add baseline: "Improve call response rate from [X]% to 90% within 3 minutes" + +Overall: 4/10 — rewrite recommended. Shall I draft improved versions? +``` + +**Starting from a vague idea?** The plugin guides you through structured questioning and suggests OKR aligned with your strategic context — because it already knows your tildelingsbrev goals and organizational priorities from onboarding. + +## The Development Process + +OKR writing is iterative. The plugin supports the full cycle: + +``` +/okr:skriv Draft OKR — guided from idea to structured output + ↓ +/okr:kvalitet Score against rubric, detect antipatterns, suggest rewrites + ↓ +/okr:kaskade Verify alignment from organization level to team + ↓ +/okr:sporing Track progress scores (0.0-1.0) during the cycle + ↓ +/okr:møter Generate check-in agendas with actual OKR status +``` + +Each command builds on context from the others. Quality-check an OKR you just wrote. Cascade it down to team level. Track it during the cycle. Generate meeting agendas with real status data. + ## Quick Start Add the marketplace: @@ -75,52 +122,48 @@ Or enable directly in `~/.claude/settings.json`: } ``` -Then start with `/okr:oppsett` to configure your organization and cycle. +Then run `/okr:oppsett` — it takes 5–15 minutes and unlocks everything else. -## Commands +## All Commands | Command | What it does | |---------|-------------| -| `/okr:skriv` | Write new OKR — guided from vague idea to scored output | -| `/okr:kvalitet` | Score existing OKR against rubric, detect antipatterns, suggest rewrites | -| `/okr:kaskade` | Cascade from organization to team, visualize alignment | +| `/okr:oppsett` | Onboarding interview — configure org, cycle, strategy, integrations | +| `/okr:skriv` | Write new OKR — guided from vague idea to scored, aligned output | +| `/okr:kvalitet` | Score existing OKR, detect 19 antipatterns, suggest rewrites | +| `/okr:kaskade` | Cascade from organization to team, visualize alignment gaps | | `/okr:sporing` | Track progress scores (0.0-1.0), generate check-in reports | | `/okr:møter` | Generate agendas for workshops, check-ins, reviews, and 1:1s | -| `/okr:innføring` | Plan OKR rollout, handle resistance, assess maturity | | `/okr:governance` | Translate tildelingsbrev to OKR, Riksrevisjon-ready documentation | -| `/okr:oppsett` | Configure organization, cycle, and Linear integration | +| `/okr:innføring` | Plan OKR rollout, handle resistance, assess maturity | -## How It Works - -Under the hood, the plugin uses 5 specialized agents, 3 context-aware hooks, and a knowledge base of 15 reference documents covering methodology, governance, antipatterns, meeting formats, and sector-specific metrics. - -Configuration is stored in `.claude/okr.local.md` in your project directory (gitignored). A hook automatically injects your org context into every conversation, so the plugin remembers your organization, cycle, and team structure across sessions. - -Linear integration is optional — enable it through `/okr:oppsett` to track OKR progress as issues with score updates. - -## Public Sector Features +## Public Sector Governance | Framework | What the plugin does | |-----------|---------------------| -| Tildelingsbrev | Parse requirements, separate OKR candidates from KPIs and compliance items | -| Riksrevisjonen | Generate documentation with baseline, target, data source, and audit trail | +| Tildelingsbrev | Parse requirements, separate OKR candidates from KPIs and compliance | +| Riksrevisjonen | Generate audit-ready docs with baseline, target, data source, owner | | Political steering | Handle mid-cycle priority changes with documented rationale | | NTP / Stortingsmelding | Cascade from national policy down to team-level OKR | +## Under the Hood + +5 specialized agents, 3 context-aware hooks, and a knowledge base of 15 reference documents covering methodology, antipatterns, governance, meeting formats, and sector-specific metrics. The plugin remembers your organization context across sessions via local configuration and automatic context injection. + +Linear integration is optional — enable through `/okr:oppsett` for OKR tracking with score updates. + ## When Not to Use This -- **Private sector** — the governance model, examples, and cycle structure are built for Norwegian public sector +- **Private sector** — governance model, examples, and cycle structure are built for Norwegian public sector - **Individual performance reviews** — OKR is a team tool; this plugin explicitly discourages individual OKR +- **Replacing workshops** — start with people and post-its, come back with your first draft for quality-checking - **Project management** — OKR sets direction, it doesn't replace your backlog or Gantt chart -- **First week of OKR** — start with a workshop and post-its, not a plugin; come back when you have your first draft ## Limitations - Not tested in a real OKR cycle beyond the author's organization -- No automated tests - Norwegian public sector context only - Linear is the only supported tracking integration -- Windows: not tested ---