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)