> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Supervisor coaching: plans, templates, and effectiveness reporting

> Author coaching plans against agents, curate the coaching-template library, close plans with an outcome, and measure the before/after KPI impact.

# Supervisor coaching: plans, templates, and effectiveness reporting

A QA score identifies a problem. A coaching plan turns it into a tracked improvement cycle: a goal, sessions against it, a close-out judgement, and a measured before/after read on the agent's metrics. This guide covers the supervisor side of that loop — the plan workspace at **Voice → Coaching Plans**, the snippet library at **Voice → Coaching Templates**, and the effectiveness report that tells you whether the coaching actually moved the agent's numbers.

Working knowledge of the QA program helps. If the auto-coaching trigger is what assigned the plan in the first place, read the auto-coaching section in [Build a contact-center QA program](/guides/quality-management-program) first — this guide deliberately does not repeat it.

## 1. The coaching loop

Plans enter your workspace two ways:

* **Auto-assigned** — a QA score below the coaching threshold, a detractor CSAT response, or a sustained intraday adherence breach writes a plan automatically. These carry a per-source tag on the goal (`[auto-coaching:qa_score]`, `[auto-coaching:csat]`, `[auto-coaching:adherence]`) and the `system:auto-coaching` sentinel owner. See [the auto-coaching loop in the QA program guide](/guides/quality-management-program).
* **Supervisor-authored** — you create the plan yourself from the Coaching Plans workspace or the API, with your own goal statement.

Once a plan exists, both kinds look and behave identically in the workspace. You attach coaching sessions to it (per-call coaching notes link to the plan), edit the goal or deadline while it is active, and close it with an outcome when the cycle ends. Treating auto-assigned plans as first-class citizens in the normal list is the point: the machine spots the pattern, the supervisor owns the follow-through.

## 2. Author a plan

Open **Voice → Coaching Plans** and choose **New plan**, or post to the API:

```bash theme={null}
curl -X POST https://api.orbit.devotel.io/api/v1/voice/coaching-plans \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_user_id": "user_agent_12",
    "goal": "Reduce average handle time by 20% over 4 weeks",
    "due_at": "2026-09-30T00:00:00Z"
  }'
```

Three fields define a plan:

* **`agent_user_id`** — the agent the plan addresses (required).
* **`goal`** — a free-form improvement statement, up to 2,000 characters. Write it so the close-out judgement is decidable: "Cut AHT by 20%" is closable; "Get better at calls" is not.
* **`due_at`** — optional target completion date (ISO 8601). Omit it for an open-ended plan you close manually.

The response carries the new plan (`201`) with `status: "active"` and you as `owner_user_id`. To adjust an active plan, `PUT /voice/coaching-plans/{id}` with any subset of `agent_user_id`, `goal`, `due_at` — a `409 PLAN_CLOSED` comes back if the plan already closed.

## 3. Work the plan list

**Voice → Coaching Plans** lists active plans first, then closed ones, ordered by due date. Filter by agent, owner, or status from the dashboard, or over the API:

```bash theme={null}
curl "https://api.orbit.devotel.io/api/v1/voice/coaching-plans?status=active&agent_user_id=user_agent_12&limit=50" \
  -H "X-API-Key: dv_live_sk_your_key_here"
```

`GET /voice/coaching-plans/{id}` returns one plan. Listing filters are `agent_user_id`, `owner_user_id`, `status` (`active` | `completed` | `cancelled`), and `limit` (default 50, max 200).

## 4. Close with an outcome, then read the effectiveness report

A plan closes with two things: a terminal status and your judgement of what happened:

```bash theme={null}
curl -X POST https://api.orbit.devotel.io/api/v1/voice/coaching-plans/cplan_abc123/close \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "completed",
    "outcome": "met",
    "outcome_notes": "AHT down from 340s to 268s; goal was a 20% cut."
  }'
```

* **`status`** — `completed` (default) or `cancelled`.
* **`outcome`** — `met`, `partial`, or `missed`. Required when closing; this is your call, and it stays a supervisor judgement by design.
* **`outcome_notes`** — optional narrative, up to 2,000 characters.

Closing the same plan twice in the same terminal state returns `200` rather than an error, so a double-click is safe. Once closed, a plan cannot be edited or re-closed to a different status (`409 PLAN_ALREADY_CLOSED`).

Your outcome judgement is subjective. The effectiveness report is the objective complement — it compares the agent's real metrics before the plan against the window after it:

```bash theme={null}
curl "https://api.orbit.devotel.io/api/v1/voice/coaching-plans/cplan_abc123/effectiveness?window_days=14" \
  -H "X-API-Key: dv_live_sk_your_key_here"
```

For each of three KPIs the report returns the before value, the after value, the delta, the percent change, and a direction (`improved` / `regressed` / `flat` / `insufficient_data`):

* **AHT (`aht_seconds`)** — talk-only average handle time; lower is better.
* **First-contact resolution (`fcr_pct`)** — share of calls where the same caller did not call back within `fcr_window_hours` (default 24); higher is better.
* **CSAT (`avg_csat`)** — mean 1–5 score from post-call surveys; higher is better.

Windows are symmetric, `window_days` long each (default 14, max 90). The **before** window is the span immediately preceding the plan's creation, so the coaching period never pollutes the baseline. The **after** window anchors on `closed_at` for closed plans; for a still-active plan it anchors on creation, giving you in-flight progress (the response flags this with `in_progress: true`). A KPI with no data in either window returns `insufficient_data` instead of a misleading zero delta.

Use this when you close: a plan you marked `met` that still shows regressed AHT deserves a look at what actually changed — and a plan you are tempted to extend might already show the improvement you were waiting for.

## 5. Curate the template library

**Voice → Coaching Templates** is the tenant's curated library of coaching snippets — the vetted phrases supervisors drop into coaching notes and whisper to agents mid-call so floor coaching stays on-brand across shift changes. The coaching-note composer on a call's detail page offers these as a picker, so a well-structured library pays off every time a supervisor writes a note.

```bash theme={null}
# List the library (paginated: page / pageSize, with total)
curl "https://api.orbit.devotel.io/api/v1/voice/supervisor/coaching-templates?category=de_escalation&page=1&pageSize=50" \
  -H "X-API-Key: dv_live_sk_your_key_here"

# Create a template
curl -X POST https://api.orbit.devotel.io/api/v1/voice/supervisor/coaching-templates \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "De-escalate angry caller",
    "category": "de_escalation",
    "body": "I hear you. Let me get this fixed for you right now.",
    "locale": "en"
  }'
```

Each template is a short snippet: `name` (up to 120 characters, unique per tenant), `body` (up to 500 characters), a `category`, and an optional `locale`. Categories:

* **`de_escalation`** — calm an upset caller
* **`discovery`** — open-ended probe questions
* **`objection`** — handle pricing or timeline pushback
* **`compliance`** — required disclosure prompts
* **`closing`** — ask-for-the-sale and wrap-up moves
* **`coaching`** — direct guidance to the agent ("slow down", "pause")
* **`other`** — catch-all

Keeping coarse categories (`coaching` for agent-behavior guidance versus `de_escalation`/`discovery`/`objection` for caller-facing moves) and fine-grained ones (`compliance` disclosures, `closing` moves) in one flat enum keeps the picker's filter simple — the whole library is one flat list a supervisor scans by category.

Edit with `PATCH /voice/supervisor/coaching-templates/{id}` (any subset of fields; set `is_active: false` to archive rather than delete). `DELETE` removes a template outright. The list defaults to active templates only; pass `include_archived=true` to audit the archive. The library caps at 1,000 templates per tenant (`409 TEMPLATE_LIMIT_EXCEEDED`), and a duplicate name returns `409 TEMPLATE_NAME_CONFLICT`.

## 6. Who sees plans, who edits templates

The two surfaces have deliberately different role gates:

* **Plans**: owners, admins, and supervisors can create, edit, close, and read any plan. Agents see plans addressed to them and their own effectiveness report; an agent reading another agent's plan gets `403`.
* **Templates**: only owners and admins curate the library — a supervisor without the admin role gets `403` at the route layer. This keeps the vetted-phrases list tight; supervisors consume the library from the coaching-note composer.

Agents acknowledging individual coaching notes on their calls is a related but separate surface (per-call coaching notes, not plans).

## 7. Example end-to-end flow

A supervisor's week with the loop closed:

1. An evaluation on agent `user_agent_12` finalizes at 65 — below the 70 threshold — and the platform writes an auto-assigned plan tagged `[auto-coaching:qa_score]`.
2. The supervisor opens **Voice → Coaching Plans**, sees the new active plan at the top of the list, and edits the goal to name the actual gap.
3. Reviewing the flagged call, the supervisor writes a coaching note on the call's detail page and drops in the "Ask discovery question" snippet from the template picker rather than free-typing it.
4. A week later the supervisor runs `GET /voice/coaching-plans/{id}/effectiveness` — AHT improved 12%, FCR flat, CSAT up — and closes the plan as `met` with a short note. The response cites whichever KPI moved, so the close-out notes read like evidence, not vibes.

## Adding this page to your program

Coaching plans close the loop that QA scoring opens: rubric → score → plan → measured outcome. Wire the template library once, and every supervisor working a note or a whisper draws from the same vetted set.

## See also

* [Build a contact-center QA program](/guides/quality-management-program) — the auto-coaching trigger thresholds and the scoring loop upstream of plans
* [Quality Management API](/api-reference/quality) — the evaluation lifecycle that feeds the loop
* [Agent assist: whisper coaching](/guides/agent-assist-whisper-coaching) — mid-call whisper surface the template library also serves
* [Error codes](/api-reference/error-codes) — `409` state-conflict and `403` role shapes