Okr progress narrator

OKR Progress Narrator

This skill takes raw OKR data — tables, lists, or free-form notes with objectives, key results, current values, and targets — and converts them into a structured narrative progress update in okr-update-YYYY-MM-DD.md. The output is designed to be shared directly with stakeholders: executive summary, per-objective narrative, KR status table, risks, and next steps.

Input:

• OKR data as a file (.md, .txt, .csv) or pasted text in chat
• Optional: period label (Q1 2026, Sprint 12), audience (CEO, board, team), tone

Output:

• okr-update-YYYY-MM-DD.md — narrative update with executive summary, per-objective sections, and risk block

---

Language Detection

Detect the user's language from their message and OKR data:

• If Russian (or Cyrillic content): respond and write the output document in Russian, using the output template below with translated section headers (e.g., "Итоговая сводка", "Цели", "Ключевые риски", "Следующие шаги")
• If English: respond and write the output document in English with standard headers
• If ambiguous: use the language of the trigger phrase
• Translate objective/KR names to the output language if the source is mixed-language

---

Instructions

Step 1: Validate and Parse Input

1. Identify the input source:

   • File path provided: Read the file. Supported formats: .md, .txt, .csv
   • Text pasted in chat: Use the message content directly
   • No input provided: Ask the user via AskUserQuestion to provide OKR data (file or paste)

2. Parse OKR structure — detect one of these layouts:

   • Markdown table: columns map to Objective / Key Result / Current / Target / %Progress / Status / Notes
   • Indented list: Objective: or O1: as headers, - KR: or KR1.1: as children
   • CSV/TSV: use header row to identify columns
   • Free-form text: extract Objective/KR pairs using keyword matching (Objective, Goal, KR, Key Result, Target, Цель, КР, Результат)

3. For each Key Result, identify:

   • Name / description
   • Current value (numeric or qualitative)
   • Target value (if present)
   • Direction: whether higher or lower values are better (default: higher is better)
     • If metric name contains keywords like "churn", "rate" (in negative context), "cost", "time", "latency", "errors": assume lower is better
     • Otherwise: higher is better
   • % progress (compute if current + target present):
     • If higher is better: round(current / target * 100)
     • If lower is better and current ≤ target: ✅ exceeded (goal met)
     • If lower is better and current > target: shortfall percentage = round(((current - target) / target) * 100) (used to classify severity, not as actual progress)
   • Status (on track / at risk / off track) — use provided value, or derive from % (see Step 2)
   • Notes / context (optional)

4. If file cannot be read or OKR structure is unrecognizable:

   • Stop. Report: "Could not recognize OKR structure in [filename / input]. Please provide data with Objective and Key Result fields."

5. Capture optional parameters:

   • Period: from user message or file metadata (e.g., "Q2 2026", "April")
   • Audience: CEO / board / team / general (default: general)
   • Tone: formal / conversational (default: formal)
   • Focus: all / at-risk-only / highlights-only (default: all)

Step 2: Classify Status

For each Key Result:

1. If status is explicitly provided in the data → use it as-is
2. If status is absent but a qualitative marker is present (e.g., "done", "completed", "✅", "achieved"):
   • Mark as ✅ exceeded if the description indicates completion or overachievement
3. If status is absent but notes or context suggest risk (e.g., "blocked", "slipped", "at risk", "delayed", "behind"):
   • Mark as 🟡 at risk (even if percentage is on track)
   • Exception: if notes clearly describe a temporary issue and the underlying metrics are strong, use percentage-based classification
4. If status is absent but % progress is computable:
   • For "higher is better" metrics:
     • Determine metric category and apply appropriate threshold:
       • Business-critical metrics (keywords: "revenue", "MRR", "ARR", "sales", "deal", "customer value", "engagement", "retention", "growth"): ≥ 85% on track
       • All other operational/technical metrics: ≥ 70% on track
     • Based on category:
       • ≥ threshold: 🟢 on track
       • 50%–(threshold-1)%: 🟡 at risk
       • < 50%: 🔴 off track

       • 100%: ✅ exceeded

   • For "lower is better" metrics (e.g., churn, cost, latency):
     • If current ≤ target: ✅ exceeded (goal met)
     • If current > target: classify by shortfall percentage = ((current - target) / target) * 100
       • Shortfall > 20%: 🔴 off track (significantly worse than target)
       • Shortfall 10–20%: 🟡 at risk (moderately worse than target)
       • Shortfall ≤ 10%: 🟢 on track (slightly worse but within acceptable margin)
5. If neither status nor numeric data is available:
   • Mark as ⬜ no data — do not invent a status

Derive Objective status:

• 🟢 if all KRs are on track or exceeded
• 🟡 if any KR is at risk
• 🔴 if any KR is off track
• ⬜ if all KRs have no data

Step 3: Generate Narrative

For each Objective:

1. Write a narrative paragraph (2–4 sentences):

   • What has been achieved so far
   • What the current state implies (momentum, risk, or completion)
   • If notes/context are available → weave them in naturally
   • Do NOT repeat exact numbers already shown in the KR table
   • Do NOT invent reasons for low progress if not provided in data

2. Adapt to audience:

   • CEO / board:
     • Lead with business impact and strategic implications
     • Skip implementation details, engineering blockers, tactical issues
     • Use outcome-focused language: "revenue target within reach", "market opportunity", "delivery risk identified", "strategic pivot needed"
     • Emphasize why each KR matters to the business
     • For at-risk items: state the business impact and mitigation approach (if known)
   • Team: Include operational detail, blockers, dependencies, and next steps if present
   • General (default): Neutral business tone. Balanced detail — progress + context without excessive implementation specifics

3. Apply focus filter if specified:

   • at-risk-only: include only 🟡 and 🔴 objectives in per-objective sections
   • highlights-only: include only 🟢 and ✅ objectives
   • all (default): include all objectives

Edge Cases:

• KR with % > 100: show as-is, mark ✅ exceeded, phrase as achievement in narrative (e.g., "exceeded target by X%")
• KR with no numeric data and no notes: write "Data not yet reported for this period"
• All KRs are 🟢 or ✅: omit "Key Risks" section entirely; do not force a risk if none exists
• Only 1 KR with no parent Objective: group under a generic "Overall Metrics" (or in Russian: "Ключевые метрики") objective header; create a single objective section
• Mixed languages in data (EN objective names + RU notes): normalize to the output language (use output language setting from Step 1); translate objective/KR names and notes if needed

Step 4: Generate Executive Summary

Write 2–4 sentences covering:

1. How many objectives are on track / at risk / off track (e.g., "2 of 3 objectives are on track")
2. Top highlight: the best-performing KR or achieved milestone
3. Top risk: the most critical at-risk or off-track item (skip if none)

Keep the summary self-contained — it should make sense without reading the full document.

Step 5: Compile Document

Assemble the output using the template below. Apply these rules:

• Omit "Key Risks" section if all KRs are on track (🟢) or exceeded (✅); always include it if any KR is 🟡 or 🔴
• Omit "Next Steps" section if no next-step data, action items, or blockers are present in the input or notes
• Use period label if provided (e.g., "Q2 2026", "April"); otherwise use "Current Period"
• Round all percentages to nearest whole number
• If audience is CEO: ensure narrative is outcome-focused and strategic; remove tactical details

Step 6: Save Output

1. Write file as okr-update-YYYY-MM-DD.md (today's date)
2. Save to:
   • The folder containing the input file (if file was provided)
   • The working directory (if text was pasted)
3. Confirm: "Saved: okr-update-[date].md — [N] objectives, [N] KRs. [N] at risk."

---

Output Format

# OKR Progress Update — [Period]
**Prepared:** YYYY-MM-DD
**Audience:** [if specified]

---

## Executive Summary

[2–4 sentences: overall status, top highlight, top risk]

---

## Objectives

### [Objective 1 Name] — 🟢 On Track

[Narrative paragraph: 2–4 sentences on progress, momentum, notable context]

| Key Result | Current | Target | Progress | Status |
|------------|---------|--------|----------|--------|
| [KR 1.1]   | [value] | [value]| [%]      | 🟢     |
| [KR 1.2]   | [value] | [value]| [%]      | 🟡     |

---

### [Objective 2 Name] — 🔴 Off Track

[Narrative paragraph]

| Key Result | Current | Target | Progress | Status |
|------------|---------|--------|----------|--------|
| [KR 2.1]   | [value] | [value]| [%]      | 🔴     |

---

## Key Risks

| Key Result | Objective | Status | Context |
|------------|-----------|--------|---------|
| [KR name]  | [O name]  | 🔴     | [note]  |

---

## Next Steps

- [Next planned action if present in data]

---
*Generated by okr-progress-narrator · [date]*

---

Negative Cases

• No input provided → ask for OKR data via AskUserQuestion; do not generate a blank document
• File path provided but file does not exist → stop; report exact path checked; ask user to verify
• Input file has no recognizable OKR structure → stop; report the file name; suggest format hint
• All objectives have no data (⬜) → generate document but flag in Executive Summary: "No quantitative data available for this period — narrative based on qualitative notes only"
• Period specified but data appears to be from a different period → include a note: "Note: data timestamps suggest this may be from [inferred period]. Review before sharing."