escalation_brief v1.0.0

name: escalation_brief description: "Turn a long support thread into a one-page, decision-ready escalation brief: the customer's ask in their own words, what was tried, current state, severity scored from impact and urgency, and a single clear ask with an owner and deadline. Use when escalating a ticket to engineering, leadership, security, billing, or a specialist team, when a case has stalled, or when someone asks for an escalation summary or handoff."

Escalation Brief

Purpose

Most escalations fail for a boring reason: the receiver has to re-read the whole thread to find out what decision they are being asked to make. This skill compresses a thread into one page that a busy receiver can act on in two minutes, without asking the customer to repeat anything and without re-running work that was already done.

It does three things a plain summary does not:

1. Tests whether escalation is warranted at all, using explicit criteria.
2. Scores severity from impact and urgency with a rubric, instead of copying the customer's frustration level or the agent's guess.
3. Ends with one primary ask, a named owner, a deadline, and a recommendation, in handoff templates matched to the receiving team.

Workflow

1. Decide: escalate, hand off, or keep working

Escalation and a routine handoff are not the same thing. A handoff moves ownership for continuity. An escalation asks for authority, expertise, or urgency the current owner does not have.

Escalate when at least one is true:

• A bug, outage, integration failure, or data problem likely needs code, infrastructure, or specialist work.
• Progress is blocked on a product, policy, security, commercial, or leadership decision.
• There is real risk to trust, retention, compliance, security, privacy, data integrity, or reputation.
• Several customers show the same underlying failure, or the same customer has hit it repeatedly.
• The case has stalled past its expected response path and needs an ownership or urgency intervention.
• A commitment made to the customer needs an internal answer, deadline, or decision owner.

Do not escalate yet when:

• A documented answer or workaround resolves the case.
• The customer needs guidance, configuration help, or expectation setting, and support can give it.
• Evidence is too thin to act on. Collect the missing evidence first, or label the brief evidence-limited and say exactly what is missing.
• The only reason is that the customer is loud. Volume is a fact to record, not a severity score.

If none of the escalation criteria hold, say so, keep the case, and write the handoff version instead (see references/handoff-templates.md).

2. Extract, do not paraphrase away, the customer's ask

• Pull the customer's ask in their own words. Quote it exactly, keep it short, and note the date and channel. If they asked for three things, list all three and mark which one is blocking.
• Separate what they asked for from what they need. A request for a refund may be a request to be made whole after a failed export. Record both lines: Asked for: and Underlying need, if different:.
• Record identifiers the receiver needs to act without asking back: ticket or case ID, account ID, affected user or site, plan or version, environment, and time zone. Leave out personal data the receiver does not need.

3. Build the evidence spine

Work through the thread in time order and fill these fields. Write "not in thread" where something is absent. Never fill a gap from memory or assumption.

• First observed: timestamp with time zone, and who reported it.
• Expected result vs actual result, in plain words.
• Reproduction: numbered steps, or "not yet reproduced" plus the conditions that seem to matter.
• Verified facts: things directly observed, logged, or confirmed by the customer.
• Hypotheses: suspected causes, each labelled unconfirmed, with what would confirm or rule it out.
• Tried and ruled out: each attempt, what changed, and what it eliminated. A failed attempt is evidence. Do not drop it because it did not work.
• Evidence location: links or references to logs, screenshots, recordings, or linked tickets. Point to them, do not paste large dumps into the brief.
• Promises already made: what the customer was told, by whom, and by when.

4. Score severity from impact and urgency

Score impact and urgency separately, then read the priority off the matrix in references/severity-rubric.md.

• Impact: how many people or accounts are affected, whether a core function is down or degraded, whether data is at risk, and whether a workaround exists.
• Urgency: how fast harm grows if nothing happens, whether a deadline or SLA clock is running, and whether a workaround buys time.

State the result as a level plus the reason, for example: "Sev 2 / P2. Core export function fails for one enterprise account, no workaround, renewal export due Friday." If the local team uses a different scale (Cisco Sev 1 to 4, Atlassian SEV 1 to 3 or 1 to 5, ITIL P1 to P5), map to that scale and say which scale you used.

Never inflate a level to jump a queue. A brief that cries Sev 1 for a Sev 3 problem trains receivers to ignore the next real one.

Copy response and resolution targets from the team's own SLA table. If you do not have that table, write "SLA target not available" rather than inventing a number.

5. Write the one primary ask

The brief exists to get one thing decided or done. Write it as a verb, an owner, and a deadline:

• Weak: "Please look into this."
• Usable: "Engineering: confirm by Wed 14:00 CT whether the export failure is the known queue bug #4821 or a new defect, so support can give the customer a date."
• If there are several asks, sequence them. Put the blocking one first and list the rest under "After that".
• Add a recommendation when you have a basis for one: "Recommend we offer the manual export workaround now and fix the root cause in the next release, because the customer can wait for the fix but not for the data."
• Name the fallback: what happens, and what the customer gets told, if the deadline passes with no answer.

6. Assemble the brief on one page

Use the template in references/handoff-templates.md for the receiving team. See references/worked-example.md for a filled brief from a condensed thread, and assets/example-brief.json for the same case in the validator's JSON format. Keep the whole brief to about 450 words plus the timeline table. If it does not fit, the thread detail belongs in the ticket, linked from the brief, not in the brief itself.

Order matters. Decision and ask go at the top, following the logic of structured handoff formats such as SBAR (Situation, Background, Assessment, Recommendation): the receiver gets the situation and the request first, then the background that supports it.

7. Run the quality gate

Before sending, check every line in the checklist in references/severity-rubric.md, section "Pre-send gate". Then, if the brief is supplied as JSON, run the validator:

python3 ~/workspace/skills/escalation-brief/bin/brief.py validate brief.json
python3 ~/workspace/skills/escalation-brief/bin/brief.py render brief.json
python3 ~/workspace/skills/escalation-brief/bin/brief.py score --impact high --urgency medium

validate reports missing fields, vague asks, inflated severity mismatches, and word count. render prints the one-page brief in Markdown. Fix every error it reports. Warnings can ship only if you can explain them in the brief itself.

8. Close the loop with the customer

Escalation is not silent from the customer's side. Before or at the same time as the internal brief goes out, tell the customer: what is happening, who now owns it, and when they will next hear from you. Use the customer-facing line in the template. Then keep the ticket as the system of record: the brief points to the ticket, it does not replace it.

Output Contract

Deliver one brief with these sections, in this order:

1. Header: ticket ID, severity and priority with the scale named, receiving team or named owner, date prepared, next update due.
2. Decision needed: one sentence.
3. TL;DR: who is affected, what is broken, and the business effect, in two sentences at most.
4. Customer's ask, in their own words: exact quote, plus underlying need if different.
5. Impact and scope: who and how many, core function affected, workaround status, clock or deadline running.
6. Current state: where the case stands right now, last action, last customer update.
7. Tried and ruled out: bulleted attempts with outcomes.
8. Verified facts / Open hypotheses: two short lists, kept separate.
9. Timeline: 3 to 8 dated entries.
10. The ask: primary ask with owner and deadline, recommendation, fallback if the deadline slips.
11. Customer update sent: the line sent to the customer and the promised next update time.

Length: one page, roughly 450 words plus tables. Attach or link evidence, do not embed it.

Operating Rules

• Quote the customer exactly for their ask. Paraphrase everything else.
• Keep verified facts and hypotheses in separate lists. Never present a suspected cause as a confirmed root cause.
• Record failed attempts. What was ruled out is half the value of the brief.
• Score severity from impact and urgency, not from tone, account size alone, or how long the thread is. State the scale you used.
• One primary ask per brief, with a named owner or role, a deadline with time zone, and a recommendation where you have grounds for one.
• Include only the personal data the receiver needs to act. Account and ticket identifiers yes, unrelated personal details no.
• Put timestamps in the receiver's time zone or UTC, and say which.
• Do not invent SLA targets, bug numbers, dates, or commitments. Write "not available" or "not in thread" instead.
• If evidence is thin, label the brief evidence-limited at the top and name the missing item. Do not hide the gap.
• Tell the customer what is happening and when they will hear next. An internal escalation with no customer update is unfinished work.
• Keep the ticket as the record. The brief is a decision document that links back to it.