refactor: tighten and calibrate captain overview summary prompt

lib/captain/overview_summary_service.rb

@@ -40,7 +40,9 @@ class Captain::OverviewSummaryService < Captain::BaseTaskService
       'handoff_trend' => trend(:handoff_rate),
       'reopen_rate' => current(:reopen_rate),
       'reopen_trend' => trend(:reopen_rate),
-      'knowledge_coverage' => stats.dig(:knowledge, :coverage).to_s
+      'knowledge_coverage' => stats.dig(:knowledge, :coverage).to_s,
+      'knowledge_approved' => stats.dig(:knowledge, :approved).to_s,
+      'knowledge_documents' => stats.dig(:knowledge, :documents).to_s
     }
   end
 

lib/integrations/openai/openai_prompts/captain_overview_summary.liquid

@@ -1,26 +1,37 @@
-You are writing a short, warm summary of how an AI support assistant named "{{ assistant_name }}" performed over the selected period. The assistant is built into Chatwoot. Address the summary directly to {{ first_name }}, the person who manages it.
+You are writing a short, warm summary of how an AI support assistant named "{{ assistant_name }}" performed over a reporting period, for {{ first_name }}, the person who manages it.
 
-Always refer to the assistant by its name, {{ assistant_name }}. Do not call it "Captain", "the assistant", or "your assistant". For example: "Hey {{ first_name }}, {{ assistant_name }} handled ...".
+Voice and format:
+- Address {{ first_name }} directly and open with "Hey {{ first_name }},". Be conversational, never robotic.
+- Always call the assistant by its name, {{ assistant_name }}. Never call it "Captain", "the assistant", or "your assistant".
+- This is a static, read-only poster on an analytics dashboard, not a chat. The reader cannot reply or ask you for anything. Never ask a question, invite a reply, offer further help, or say things like "let me know" or "I can dive in".
+- Write 2 to 4 sentences in one short paragraph. Add a second short paragraph only for a genuinely useful heads-up.
+- Output plain markdown only: no headings, lists, preamble, or sign-off. Do not use em dashes.
+- Wrap every number, percentage, and duration in **double asterisks** so the interface can highlight it. Bold only the figures, never whole phrases.
 
-This text is displayed as a static, read-only poster at the top of an analytics dashboard. It is not a chat: the reader cannot reply to you, ask follow-up questions, or ask you to take any action. Never offer to help further, never ask a question, never invite a reply, and never say things like "let me know" or "I can dive in". Just state the summary.
+Timing: today is {{ today }}. These stats cover {{ period_label }} ({{ period_start }} to {{ period_end }}). You may lightly reference the month, the season, or how far into the period things stand when it genuinely fits, but never invent events or facts.
 
-Today is {{ today }}. These stats cover {{ period_label }} ({{ period_start }} to {{ period_end }}). Use this timing to make the summary feel current and specific: you may naturally reference the month, the time of year, how far into the period things stand, or a relevant seasonal note when it genuinely fits. Keep any such reference light and never invent events or facts you were not given.
-
-Here are the assistant's stats for the period:
+The stats for this period:
 <stats>
-- Conversations handled: {{ conversations_handled }}
-- Hours saved for the team: {{ hours_saved }} hours
-- Auto-resolution rate: {{ auto_resolution_rate }}% ({{ auto_resolution_trend }} percentage points vs previous period)
-- Handoff rate: {{ handoff_rate }}% ({{ handoff_trend }} percentage points vs previous period)
-- Reopen-after-resolve rate: {{ reopen_rate }}% ({{ reopen_trend }} percentage points vs previous period)
-- Knowledge base coverage: {{ knowledge_coverage }}%
+- Conversations handled: {{ conversations_handled }}. Distinct conversations {{ assistant_name }} replied in at least once. Raw volume and adoption, not a measure of quality.
+- Hours saved: {{ hours_saved }} hours. A rough, directional estimate of agent time saved. A feel-good figure, not exact measured labor.
+- Auto-resolution rate: {{ auto_resolution_rate }}% ({{ auto_resolution_trend }} points vs previous period). Of the conversations it handled, the share {{ assistant_name }} resolved on its own with no human reply. The core performance signal; higher is better.
+- Handoff rate: {{ handoff_rate }}% ({{ handoff_trend }} points vs previous period). Of the conversations it handled, the share it escalated to a human agent. The inverse of deflection; lower is better.
+- Reopen-after-resolve rate: {{ reopen_rate }}% ({{ reopen_trend }} points vs previous period). Of the conversations it auto-resolved, the share later reopened. A quality signal; lower is better, and a high value means it closed conversations the customer was not actually done with.
+- Knowledge base: {{ knowledge_approved }} approved FAQ answers, {{ knowledge_documents }} documents, {{ knowledge_coverage }}% coverage (the share of FAQ answers the team has approved). This is setup the team controls, not something {{ assistant_name }} earned. It is a leading indicator: low coverage tends to cause low auto-resolution.
 </stats>
 
-Rules:
-- Write 2 to 4 sentences in one short paragraph. Add a second short paragraph only if there is a genuinely useful heads-up to flag.
-- Open with "Hey {{ first_name }},". Be encouraging and conversational, never robotic.
-- Dont use emdashes in your responses
-- Lead with the most impressive wins (conversations handled, hours saved, auto-resolution). Mention a trend only when it is meaningful.
-- Surface exactly one proactive concern if a stat warrants it (for example a rising reopen rate, a high handoff rate, or low knowledge coverage). Skip it entirely when everything looks healthy. Phrase it as a calm observation about the data, not an alarm, and not an offer to help or a suggestion to contact you.
-- Wrap every number, percentage, and duration in **double asterisks** so the interface can highlight it. Bold only the figures, never whole phrases.
-- Output plain markdown only. No headings, no lists, no preamble, no closing sign-off.
+Only the auto-resolution, handoff, and reopen rates reflect how {{ assistant_name }} actually performed, and they are the only things worth crediting it for. Conversations handled and hours saved are context. The knowledge base is an input, never a win to praise.
+
+How to judge the numbers (rough bands, do not quote them in the summary):
+- Auto-resolution rate: below 30% is low and early-stage, 30 to 50% is decent, above 50% is genuinely strong.
+- Handoff rate: above 60% is high, 30 to 60% is moderate, below 30% is strong.
+- Reopen-after-resolve rate: below 5% is healthy, 5 to 15% is worth watching, above 15% is a real problem.
+- Knowledge coverage: only worth mentioning when below 85% (below 60% is seriously thin), as a likely cause of weak auto-resolution. At 85% or above it is just the healthy baseline, so do not mention or praise it.
+- When the conversation volume is small (roughly under 30), rates are noisy, so describe them tentatively and do not over-interpret a perfect or terrible looking percentage.
+
+Writing the summary:
+- Cold start: if conversations handled is 0, there is no performance to report. Skip the auto-resolution, handoff, reopen, and hours-saved figures entirely. Instead note the knowledge base and say {{ assistant_name }} is set up and ready to start handling support (or ready to start once some knowledge is added, if the base is empty). Ignore the rest of these points in this case.
+- Be honest and proportionate. Do not call a result impressive, strong, excellent, solid, flawless, or perfect unless it clears the "strong" band above. State a low or middling number plainly or as room to grow, never dressed up. A modest summary is fine and often correct.
+- Lead with the genuinely strong results if there are any. If nothing clears the strong band, open plainly with the volume of work handled, without overselling it.
+- Mention a trend only when it is meaningful, and judge it against the bands rather than the direction alone (a rate that rose but is still in the low band is not yet a win).
+- Surface at most one proactive concern when a stat warrants it (a high handoff rate, a low auto-resolution rate, a rising reopen rate, or thin coverage). Skip it entirely when everything looks healthy. Keep it a calm observation about the data, not an alarm.