Template: customer escalation

(needs modelrig 0.13.0 or newer) Grade a drafted reply to an escalated customer — a complaint, a refund demand, a missed promise — before the employee who owns the escalation sends it. This page is one of the use-case templates: a starting point, not a finished grader. The reply is usually one step of a process that waits on the customer or on an employee, and each approval the employee records teaches the grader and, through the task's review gate, earns the reply less review over time — never for the cases you floor at high_risk in code. The machine-readable source is node_modules/modelrig/templates/customer-escalation.json (0.13.0 or newer).

Does this task fit?

Customer escalations fit the shipped teach → calibrate → grade → optimize loop when four conditions hold. (1) Each drafted reply is recorded under one task (for example escalation-reply-draft) — often a step of a process opened with rig.process while the escalation waits on the customer or on an employee — and the employee who owns the escalation approves, edits or rejects it from your own dashboard with rig.approval, which is what teaches the grader. (2) Your support lead can write down the policies an escalation reply must follow (refunds, credits, exceptions, who may grant them), which is the grading guide below. (3) The draft is grounded in the case history your code passes in — the customer's messages, the order or account state, earlier replies — so the grader can check that the issue was understood. (4) Escalations arrive often enough that approvals add up; the review gate only reduces review once the grader is calibrated, and you can keep a high-risk floor in code so the riskiest cases are always reviewed. This template is a starting point for each of those, not a claim that escalations are solved — fill in your own policies before you rely on it. Your code sends the reply; ModelRig never does.

Starter schema

Replace every TODO with your own taxonomy; the enum slots ship without values on purpose, so an unfilled template refuses to look finished.

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$comment": "STARTER SCHEMA for ONE drafted escalation reply. Replace every TODO with your own values before use. The template runs as-is: free-text fields validate immediately. TODO markers show where adding your own enum values tightens grading to your playbook; do not copy example words from the docs.",
  "title": "EscalationReply",
  "type": "object",
  "additionalProperties": false,
  "required": [
    "issue_summary",
    "reply",
    "next_step",
    "escalate_to_human"
  ],
  "properties": {
    "issue_summary": {
      "type": "string",
      "description": "One sentence stating the customer's problem as the draft understood it — the grader compares it with the case history."
    },
    "reply": {
      "type": "string",
      "description": "The reply as it would be sent to the customer."
    },
    "next_step": {
      "type": "string",
      "description": "What happens next and who does it (a refund issued, a callback booked, a replacement shipped). TODO(enum): constrain this to YOUR own next-step types by adding an \"enum\": [ ... ] here. It runs as free text immediately.",
      "$comment": "TODO(enum): add your next-step types as the enum for this field."
    },
    "escalate_to_human": {
      "type": "boolean",
      "description": "True when the case needs a person beyond the reviewer (a legal threat, a safety issue, a request outside policy). Pairs with the escalated-when-needed criterion."
    },
    "policy_refs": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Optional: the ids of your own policy articles the reply relies on, so the grader can check the policy was applied."
    }
  }
}

Starter grading guide

The starter criteria run as written — sharpen each one in your team's own words as you grade. They are in the exact jsonb shape the set_task_settings write path validates — binary checks, each with a one-sentence pass and fail. There is no pass_threshold here: that lives in the route's grade: block.

issue_understood — The customer's issue is understood

• Pass: the draft states the customer's actual problem, including the detail that made them escalate, as the case history shows it.
• Fail: The draft answers a different or smaller problem, misses why the customer escalated, or repeats an answer they already rejected.

policy_correct — The policy is applied correctly

• Pass: every refund, credit, exception or explanation in the draft is what your written policy allows for this case, stated accurately.
• Fail: The draft offers more or less than your policy allows, quotes a policy wrongly, or invents one.

empathetic — Acknowledges the customer with real empathy

• Pass: the draft acknowledges the impact on the customer in plain, specific words and takes responsibility where your company is at fault.
• Fail: The draft is defensive, blames the customer, or uses a generic apology that ignores what happened.

next_step_clear — The next step is clear

• Pass: the draft tells the customer exactly what happens next, who does it and when, and what, if anything, they need to do.
• Fail: The draft ends without a concrete next step, or promises a step with no owner or time.

escalated_when_needed — Handed to a person when the case needs one

• Pass: a case with a legal threat, a safety issue, a request outside policy or a repeat failure is routed to the right person rather than answered alone.
• Fail: The draft answers a case that needed a person on its own, or hands off a routine case it could have resolved.

The guide's escalation band starts at epsilon: 0.1: a grade within that distance of the route's pass threshold is treated as judge-uncertain and sent to a human. It is a starting band — tune it as your grader calibrates.

Golden checklist

Roughly twenty examples that cover:

• One well-handled reply per common escalation reason — a late order, a billing error, a broken product — the ordinary case done right.
• A reply that answers the original question but misses why the customer escalated.
• A refund or credit request your policy allows, handled correctly — and one it does not allow, refused with a clear reason.
• A very angry customer handled well, so empathy is judged on the hard cases rather than the easy ones.
• A case that must go to a person (a legal threat, a safety issue, a third failure) and a routine case that should not.
• A reply with a vague next step, so the guide learns what a concrete one looks like.
• Aim for roughly twenty goldens total, weighted toward the boundaries above rather than the easy centre.

Escalation starter

Start by keeping every draft in front of the employee who owns the escalation: set the task's review gate to always, or to earned so it only reduces review once the grader is calibrated against their approvals, and declare a high_risk floor in code for legal, safety or high-value cases so those are always reviewed. The machine-side band lives in starter_guide.escalation.epsilon: a grade within that distance of your task's pass threshold is treated as grader-uncertain and sent to the human queue. The 0.1 here is a starting band — widen it while you build trust, narrow it as your grader calibrates.

Apply it

By hand: record each drafted reply under one task — tags: { step: "escalation-reply-draft" } on the call — and write the starter criteria into that task's grading guide in your support lead's words. Record the owner's verdict with rig.approval, ask rig.reviewDecision({ task, subjectKey, floor }) before a reply goes out (pass floor: "high_risk" for legal, safety or high-value cases), and post what happened later — resolved, reopened — with rig.outcome.

From a coding agent: scaffold_skill_receipts drafts this guide for a skill whose description mentions escalations or complaints; set_task_settings applies it and set_review_gate sets the policy. See Make a skill measurable.