@damiangilgonzalez/harness 1.3.7

package/skills/csharp-dotnet/scripts/verify.sh

@@ -0,0 +1,90 @@
+#!/usr/bin/env bash
+#
+# verify.sh - local quality gate for a .NET solution or project (superset of CI).
+#
+# Usage:
+#   cd <your-solution-or-project-root>   # dir with a .sln or .csproj
+#   ./verify.sh
+#
+# Runs: dotnet format --verify-no-changes (style), dotnet build -warnaserror
+# (compile + analyzers + NRT warnings as errors), dotnet test (xUnit/NUnit),
+# and dotnet list package --vulnerable --include-transitive (NuGet vuln scan).
+# A missing `dotnet` is skipped with a yellow warning (not a failure).
+# Real problems (unformatted code, build/test failures, known vulnerabilities)
+# exit non-zero. Read-only: never mutates your source.
+#
+# Portability: runs on stock macOS bash 3.2 (no mapfile, no associative arrays).
+
+set -euo pipefail
+
+# Colors only when stdout is a TTY (keeps logs/CI output clean).
+if [ -t 1 ]; then
+  YELLOW=$'\033[33m'; RED=$'\033[31m'; GREEN=$'\033[32m'; RESET=$'\033[0m'
+else
+  YELLOW=''; RED=''; GREEN=''; RESET=''
+fi
+
+failed=0
+
+have() { command -v "$1" >/dev/null 2>&1; }
+warn() { printf '%s[skip]%s %s\n' "$YELLOW" "$RESET" "$*"; }
+fail() { printf '%s[fail]%s %s\n' "$RED" "$RESET" "$*"; failed=1; }
+ok()   { printf '%s[ ok ]%s %s\n' "$GREEN" "$RESET" "$*"; }
+info() { printf -- '----- %s\n' "$*"; }
+
+# Must run from a solution or project root. An empty/clean dir with no project
+# is not a failure - nothing to check, exit 0.
+sln_count=$( (ls ./*.sln ./*.slnx 2>/dev/null || true) | wc -l | tr -d ' ')
+csproj_count=$( (ls ./*.csproj 2>/dev/null || true) | wc -l | tr -d ' ')
+if [ "$sln_count" = "0" ] && [ "$csproj_count" = "0" ]; then
+  warn "no .sln/.slnx or .csproj in $(pwd) - nothing to verify."
+  exit 0
+fi
+
+# The whole pipeline needs the dotnet SDK; without it, skip cleanly.
+if ! have dotnet; then
+  warn "dotnet SDK not found - install .NET 10 SDK to run any checks. Skipping."
+  exit 0
+fi
+
+# 1. dotnet format --verify-no-changes - style/whitespace/import order, read-only.
+info "dotnet format --verify-no-changes"
+if dotnet format --verify-no-changes; then
+  ok "format clean"
+else
+  fail "formatting issues (run: dotnet format)"
+fi
+
+# 2. dotnet build -warnaserror - compile + analyzers + nullable warnings as errors.
+info "dotnet build -warnaserror"
+if dotnet build -warnaserror --nologo; then
+  ok "build clean (analyzers + NRT)"
+else
+  fail "build failed or emitted warnings (analyzers/NRT)"
+fi
+
+# 3. dotnet test - unit + integration tests.
+info "dotnet test"
+if dotnet test --nologo; then
+  ok "tests pass"
+else
+  fail "tests failed"
+fi
+
+# 4. dotnet list package --vulnerable - known NuGet vulnerabilities are a real failure.
+#    The command exits 0 even when vulns exist, so grep the output to decide.
+info "dotnet list package --vulnerable --include-transitive"
+vuln_out="$(dotnet list package --vulnerable --include-transitive 2>&1 || true)"
+if printf '%s' "$vuln_out" | grep -qiE 'has the following vulnerable|Severity'; then
+  fail "vulnerable NuGet packages found:"
+  printf '%s\n' "$vuln_out"
+else
+  ok "no known vulnerable packages"
+fi
+
+echo
+if [ "$failed" -ne 0 ]; then
+  printf '%sFAIL:%s one or more checks failed.\n' "$RED" "$RESET"
+  exit 1
+fi
+printf '%sPASS:%s all checks passed.\n' "$GREEN" "$RESET"

package/skills/customer-support/SKILL.md

@@ -0,0 +1,170 @@
+---
+name: customer-support
+description: "Use when a live support ticket needs triage (intent, P1–P4 priority, SLA clock), an on-voice reply, not a raw template, de-escalation of an angry or churn-risk customer, or escalation with a handoff packet. NOT the help-center article it links to (that is `technical-writing`), a win-back program (`retention`), or the auto-answer bot (`chatbot`)."
+tags: [customer-support, helpdesk, ticket-triage, sla, escalation, macros, de-escalation, csat]
+recommends: [technical-writing, client-onboarding, retention, chatbot, rag, brand-voice]
+origin: risco
+---
+
+# Customer Support — Run the Desk on a Live Ticket
+
+You own the **support desk as an operation**: take an incoming ticket, assign priority and intent, start the SLA clock, draft the reply (macro or bespoke), enforce tone, and decide escalation with a clean handoff. The output is a triaged, answered ticket — human judgment, not a code artifact.
+
+## The triage-to-reply loop (the spine)
+
+Run every ticket through these six steps in order. Skipping triage to "just reply fast" is how you send the wrong tone to a P1.
+
+```text
+1 Classify intent   →  what does the customer actually want? (bug, how-to, refund, outage, rage)
+2 Set priority      →  P1–P4 (impact × urgency × account tier)
+3 Start SLA clock   →  pick the FRT target NOW, before drafting
+4 Draft reply       →  macro skeleton or bespoke; one personalized line minimum
+5 Tone / voice check →  on-brand, de-escalated, no banned phrases
+6 Escalate or send  →  trigger met? hand off with the packet. else send + log.
+```
+
+## Priority, SLA, and the escalation call
+
+The branch is at step 6. This table sets priority, both SLA clocks, and whether the ticket leaves your hands:
+
+| Signal in the ticket | Priority | First response (FRT) | Resolution target | Escalate? |
+|---|---|---|---|---|
+| Production down / data loss / payments broken / many users blocked | P1 critical | 15–30 min | ASAP, status updates every 30–60 min | Yes → tier-2/eng + the packet |
+| Enterprise/VIP account, or "cancel / refund / lawyer / unacceptable" | P1–P2 | 30 min – 1 h | Same business day | Yes → owner + tier-2 |
+| One user blocked, no workaround | P2 high | 1–2 h | Same business day | Only if unresolved past target |
+| Question with a workaround, billing query | P3 medium | 4–8 h | 1–2 business days | No, unless policy claim is unverifiable |
+| FAQ, cosmetic, feature request | P4 low | ~1 business day | Best effort | No |
+
+**Why pick the FRT target before drafting:** the SLA decides your tone and length. A P1 gets a two-line acknowledgment in 20 minutes, not a polished essay in two hours.
+
+Use **3–4 priority tiers, never a flat SLA.** Too many tiers confuse the desk; too few don't differentiate the outage from the typo (Emailmeter / Hiver, 2026-06-02).
+
+**Acknowledge fast even when you cannot resolve fast.** First-response and resolution are *separate, linked* SLAs: FRT sets the expectation, resolution is the outcome. 89% of customers feel valued by a fast first response even when the full fix takes longer (getMonetizely / Hiver, 2026-06-02). So: acknowledge inside the FRT window with an honest "here's what I know and when I'll update you," then resolve honestly. Never go silent to wait for a perfect answer.
+
+Full P1–P4 matrix by channel (email/chat/phone) lives in [`references/macros-and-sla.md`](references/macros-and-sla.md).
+
+## Macros done right
+
+A macro with **one genuinely personalized sentence raises CSAT; a verbatim template lowers it.** Macros cut first-response time 30–50%, but sent raw they read as scripted (TextExpander / Gorgias, 2026-06-02). So every macro is a skeleton you finish, not a message you forward.
+
+The 4-beat skeleton — every reply hits these in order:
+
+```text
+1 Empathy / ack   →  name the problem in their words (1 line)
+2 Answer          →  the fix, the status, or the next concrete step
+3 Next step       →  what happens now + when they'll hear back
+4 Close           →  human sign-off, door left open
+```
+
+Rules:
+
+- **Fill dynamic fields, then add one bespoke line.** Placeholders like `{{first_name}}`, `{{order_id}}`, `{{ticket_id}}`, `{{date}}` are table stakes — they are not personalization. The personalized line references *this* ticket's specifics.
+- **Never send a macro with a visible `{{placeholder}}`.** A leaked `{{first_name}}` is worse than no name.
+- **One reply, one ask.** If you need three things from the customer, you'll get one. Batch the request or sequence it.
+
+Bad → Good (info-request macro):
+
+```text
+Bad (verbatim template, robotic):
+  Dear Customer, Thank you for contacting support. We have received your
+  request. In order to assist you, please provide additional information.
+  Your satisfaction is important to us. Regards, The Support Team.
+
+Good (skeleton + one personalized line):
+  Hi Marta — sorry the export keeps failing on you. To dig in I need one
+  thing: the rough time you last hit "Export CSV" today (so I can pull the
+  matching server log). I noticed your account is on the new billing plan,
+  so this might be the same migration glitch we patched yesterday — I'll
+  confirm and get back to you within 2 hours. — Eric
+```
+
+The Good version names the feature, gives a real next step + a time, and the "new billing plan / migration glitch" line proves a human read the ticket.
+
+Full skeleton library (ack, info-request, resolved, refund, known-bug, outage, churn-save, escalation-handoff, feature-request decline, gentle-close) is in [`references/macros-and-sla.md`](references/macros-and-sla.md).
+
+## Tone and de-escalation
+
+Apply the brand voice; do not invent it here. The voice guide is authored by [`../brand-voice/SKILL.md`](../brand-voice/SKILL.md) — this skill reads it and writes the reply against it.
+
+For an angry or churn-risk ticket, de-escalation moves in order:
+
+1. **Acknowledge the feeling before the facts.** "Three days without a reply is not okay, and I get why you're frustrated" lands before any fix.
+2. **Take ownership in the first person.** "I dropped this" beats "the team was unable to." No passive voice to hide behind.
+3. **One concrete next step with a time.** Vague reassurance reads as a brush-off; "I'll have an answer by 3pm" is trust.
+4. **Match their stakes, not their volume.** Stay calm and specific. Do not argue, and never match anger with anger.
+
+Banned phrases — they escalate, not de-escalate:
+
+| Never write | Why it backfires | Write instead |
+|---|---|---|
+| "Please calm down." | Tells them their feeling is the problem. | "You're right to be frustrated — let's fix it." |
+| "As I said / as previously mentioned" | Scolds them for not reading. | Just restate it plainly. |
+| "Per our policy." (naked) | Hides behind rules, no human. | Explain the *why*, then the policy. |
+| "Unfortunately, there's nothing we can do." | Dead end, zero path. | Offer the nearest thing you *can* do. |
+| "This is a known issue." (alone) | Sounds like "we knew and didn't care." | Add the status + the ETA or the workaround. |
+
+Checklist before send: feeling acknowledged · first-person ownership · one timed next step · no banned phrase · no `{{placeholder}}` left.
+
+De-escalating *this* ticket is the job here; running a win-back or renewal **program** is `retention`.
+
+## Escalation
+
+Escalate on **explicit conditions, not vibes.** Standard tiers: T1 frontline/common, T2 specialist/complex, T3 engineering or exec/critical (Kapture / Hiver, 2026-06-02). Hand off when any trigger fires:
+
+- **Negative-language signals:** "unacceptable", "cancel", "refund", "lawyer", "chargeback".
+- **SLA at risk:** the FRT or resolution target is about to blow.
+- **Account tier:** enterprise / VIP.
+- **Confidence below threshold:** if an assisted/AI draft is below ~85% confidence on a policy or price claim, hand to a human — don't guess (swiftflutter / Kapture, 2026-06-02).
+
+**Context must travel with the escalation.** 70% of customers expect the next agent to know their history; making them repeat themselves adds 90–180 seconds per ticket (Forrester via Fini Labs, 2026-06-02). Never escalate a bare ticket link. Attach the handoff packet:
+
+```text
+HANDOFF PACKET
+- Customer + account tier:  Marta R. — Enterprise (VIP)
+- Ticket / priority:        #4821 — P1
+- One-line summary:         CSV export 500s since ~09:00; blocking month-end close.
+- Steps already tried:      Confirmed not browser/cache; reproduced on staging.
+- Customer sentiment:       Angry, has mentioned "cancel" once.
+- Collected variables:      plan=new-billing, last_export=09:14, region=eu-west
+- What I need from you:      Confirm if the billing-migration patch covers this.
+```
+
+The full escalation matrix (trigger → tier → owner) is in [`references/macros-and-sla.md`](references/macros-and-sla.md).
+
+## FAQ and KB answering
+
+**Quote the KB or escalate — never invent policy, price, or an ETA.** Hallucinated support answers produced 150+ documented legal cases by mid-2025 (cmswire / swiftflutter, 2026-06-02). The guardrail:
+
+- If the answer is in the KB, **quote it and link the article.** Don't paraphrase a refund window or a price from memory.
+- If it is not in the KB, say "let me confirm" and escalate — do not fill the gap with a plausible guess.
+- Deflection is **bounded by KB quality.** Triage-only without a strong KB deflects ~20–30%; well-organized KBs push assisted/auto resolution to 50–80% (Zendesk / Intercom / Fini Labs, 2026-06-02). A bad answer fast is worse than a correct answer slightly slower.
+
+This skill *consumes* the KB; it never writes it. If the article the customer needs does not exist, flag the gap — authoring it is a `technical-writing` job, and building the autonomous auto-answer bot on top of the KB is `chatbot` + `rag`.
+
+## Metrics — what to watch and when
+
+No single metric is sufficient; track the trio plus resolution rate (Armatis / Giva, 2026-06-02):
+
+| Metric | What it measures | When to optimize for it |
+|---|---|---|
+| **CSAT** | Transactional satisfaction; `positive ÷ total × 100` | After any single ticket; the default health signal |
+| **CES** | Customer effort, 1–7 scale | When tickets resolve but customers still churn — friction is the problem |
+| **NPS** | Relationship; promoters − detractors | Quarterly / relationship level, not per-ticket |
+| **FCR / one-touch** | Resolved in one interaction | When repeat contacts are climbing — optimize the first reply |
+
+Rule of thumb: optimize **FRT** for reassurance (the customer feeling handled), **FCR** for effort (fewer round-trips). They pull in different directions — don't chase both blindly.
+
+## Anti-patterns
+
+| Anti-pattern | Why it fails | Do instead |
+|---|---|---|
+| Send the macro verbatim | Reads as scripted, drops CSAT | Skeleton + one bespoke line + filled fields |
+| Polish for an hour, send nothing | Misses the FRT window | Acknowledge fast, resolve honestly later |
+| One flat SLA for every ticket | Outage waits behind a typo | 3–4 priority tiers with distinct FRT targets |
+| Argue with an angry customer | Volume escalates, churn rises | Acknowledge feeling, own it, give a timed step |
+| Invent a policy / price / ETA | Hallucinated answers create real liability | Quote the KB or say "let me confirm" + escalate |
+| Escalate a bare ticket link | Next agent restarts, +90–180s, anger | Attach the handoff packet every time |
+| Leave a `{{placeholder}}` in the reply | Worse than no name; signals automation | Verify all fields filled before send |
+| "Please calm down" / "as I said" | Tells them their feeling is the fault | De-escalation moves; banned-phrase swaps |
+| Promise a fix you can't verify | Breaks trust when it slips | Promise the *next update time*, not the fix |
+| Chase NPS off a single ticket | Wrong altitude metric | CSAT/FCR per ticket; NPS at relationship level |

package/skills/customer-support/evals/README.md

@@ -0,0 +1,13 @@
+# Evals — customer-support
+
+These cases are graded by an LLM judge against `cases.yaml`, run through the
+repo's eval harness. `should_trigger` and `should_not_trigger` check routing —
+that a real support ticket loads this skill while near-misses (writing the KB
+doc, the onboarding flow, the win-back program, the voice guide, the bot) route
+to their correct sibling. The `capability` case checks reply *quality*: the
+judge scores the produced triage + draft against the `must_include` rubric
+(P1 + FRT target, acknowledge-before-promise, de-escalation without banned
+phrases, no invented fix/ETA, an escalation handoff packet, the right metric).
+There is no `verify.sh` — this is a judgment skill whose output is a triaged
+ticket and a drafted reply, not a machine-checkable artifact, so the capability
+rubric carries the rigor.

package/skills/customer-support/evals/cases.yaml

@@ -0,0 +1,61 @@
+skill: customer-support
+
+# Prompts that MUST load `customer-support`. The skill handles a LIVE ticket:
+# triage (priority + intent) -> SLA clock -> draft on-voice reply -> de-escalate
+# -> escalate with a handoff packet. It never writes the KB article, the
+# onboarding flow, the retention program, or the auto-answer bot.
+should_trigger:
+  - prompt: "A customer just emailed saying our app is down and they're losing money — how should I handle this ticket?"
+    why: "Core P1 path: triage to critical, acknowledge fast inside the FRT window, then escalate to engineering with a handoff packet."
+
+  - prompt: "Give me a set of canned replies for the most common support questions."
+    why: "The macro skeleton library is a named deliverable — ready replies the agent finishes, not verbatim templates."
+
+  - prompt: "This user is threatening to cancel and leave a bad review — draft a reply."
+    why: "Non-obvious: the word 'support' never appears, but a churn-risk de-escalation reply on a single live ticket is exactly this skill (not the retention program)."
+
+  - prompt: "Redacta una respuesta para un cliente enfadado que lleva 3 días sin contestación."
+    why: "Spanish for 'draft a reply for an angry customer who's gone 3 days without a response' — de-escalation plus an SLA breach, both owned here."
+
+  - prompt: "What first-response and resolution times should we promise for high vs low priority tickets?"
+    why: "Setting tiered FRT and resolution SLA targets by priority is a named use; the P1–P4 matrix is the artifact."
+
+  - prompt: "Tracta aquest ticket de suport i decideix si l'escalo a un humà."
+    why: "Catalan for 'triage this support ticket and decide whether to escalate it to a human' — triage plus the escalation call, the spine of the skill."
+
+# NEAR-MISS prompts that must NOT load `customer-support`. Each routes to the
+# sibling that owns it. Trap: anything that BUILDS the asset around the ticket
+# (the doc, the bot, the program, the voice guide) instead of handling the ticket.
+should_not_trigger:
+  - prompt: "Write the help-center article explaining how to reset a password."
+    route_to: "technical-writing"
+    why: "Authoring the KB doc is technical-writing; customer-support only consumes the KB to answer a ticket and links the article."
+
+  - prompt: "Set up the welcome flow for customers who just signed up."
+    route_to: "client-onboarding"
+    why: "New-customer activation and welcome sequence is client-onboarding, not an inbound support ticket."
+
+  - prompt: "Build a chatbot that auto-answers support questions from our docs."
+    route_to: "chatbot"
+    why: "Building the autonomous auto-answer bot is chatbot (+ rag); this skill defines the human/assisted playbook, not the bot."
+
+  - prompt: "Define our brand's tone of voice guidelines."
+    route_to: "brand-voice"
+    why: "Authoring the reusable voice spec is brand-voice; customer-support only applies that voice to a reply."
+
+  - prompt: "Design a win-back email campaign for customers who churned last quarter."
+    route_to: "retention"
+    why: "A renewal/win-back program is retention; customer-support handles only the single churn-risk ticket in the moment."
+
+# CAPABILITY: graded against the rubric, not routing. The reply must be triaged
+# AND answered, not just classified.
+capability:
+  - scenario: "A P1 ticket: an enterprise VIP customer emails that CSV export has been throwing 500 errors since 9am, it's blocking their month-end close, they are angry and have said they'll cancel. Triage and draft how you'd handle it."
+    must_include:
+      - "Assigns P1 (critical) priority and names a first-response target in the 15–30 min range"
+      - "Acknowledges fast and sets an update time BEFORE promising a resolution or ETA"
+      - "De-escalates: acknowledges the frustration, first-person ownership, no banned phrase like 'calm down' or naked 'per our policy'"
+      - "Does NOT invent a fix, root cause, or ETA it cannot verify — offers the next update time instead"
+      - "Flags escalation to tier-2/engineering and includes a handoff packet (summary + steps tried + customer sentiment + collected variables)"
+      - "Names a metric to watch for this ticket (CSAT or FCR), not NPS"
+      - "Reply has no leftover {{placeholder}} and includes at least one personalized line specific to this ticket"

package/skills/customer-support/references/macros-and-sla.md

@@ -0,0 +1,142 @@
+# Macros, SLA matrix, and escalation — full lookup
+
+Reach for this mid-ticket. Every macro is a **skeleton you finish** — fill the
+fields, add one bespoke line, and never send with a visible `{{placeholder}}`.
+All macros follow the 4-beat order: empathy → answer → next step → close.
+
+## Macro skeleton library
+
+### 1. Acknowledgment (P1/P2, before you have the answer)
+
+```text
+Hi {{first_name}} — I've got your report about {{problem_in_their_words}} and
+I'm on it now. I don't have the full picture yet, but I'll update you by
+{{time}} whether or not it's fixed. Thanks for flagging it. — {{agent}}
+```
+
+### 2. Info request (you need one thing to proceed)
+
+```text
+Hi {{first_name}} — sorry {{feature}} is giving you trouble. To dig in I need
+one thing: {{specific_ask}}. Once I have that I can {{next_action}}. — {{agent}}
+```
+
+One ask only. If you need three, sequence them or batch them clearly.
+
+### 3. Resolved (closing a fixed ticket)
+
+```text
+Hi {{first_name}} — {{problem}} is fixed as of {{time}}. {{what_changed}}.
+Give it a try and reply here if anything still looks off; I'll keep this ticket
+open until {{date}} just in case. — {{agent}}
+```
+
+### 4. Refund / billing adjustment
+
+```text
+Hi {{first_name}} — you're right, {{what_went_wrong}}. I've issued a refund of
+{{amount}} to {{method}}; it usually lands in {{timeframe}}. Here's the why so
+it doesn't happen again: {{explanation}}. Sorry for the hassle. — {{agent}}
+```
+
+Quote the refund window from the KB — never invent it.
+
+### 5. Known bug (issue is real, fix is pending)
+
+```text
+Hi {{first_name}} — this is a real bug on our side, not anything you did, and
+the team is already on it (ref {{tracking_id}}). Current status: {{status}}.
+In the meantime this workaround gets you unblocked: {{workaround}}. I'll ping
+you the moment it ships. — {{agent}}
+```
+
+Never send "this is a known issue" alone — always pair it with status + ETA or
+a workaround.
+
+### 6. Outage (P1, multi-customer)
+
+```text
+Hi {{first_name}} — we're aware {{service}} is down and engineering is on it as
+top priority. Live status: {{status_page_url}}. I'll update you here every
+{{interval}} until it's resolved. Sorry for the disruption. — {{agent}}
+```
+
+### 7. Churn-save / de-escalation
+
+```text
+Hi {{first_name}} — {{acknowledge_the_real_grievance}}, and I understand why
+you're considering leaving. I dropped the ball on {{specific_failure}}. Here's
+what I can do right now: {{concrete_offer_or_fix}} by {{time}}. If that doesn't
+make it right, I'll loop in {{owner}} personally. — {{agent}}
+```
+
+Acknowledge the feeling, own it in first person, one timed concrete step.
+
+### 8. Escalation hand-off (to the customer, while you escalate internally)
+
+```text
+Hi {{first_name}} — this needs our {{team}} to get you a solid answer, so I've
+handed it to {{specialist}} with everything you've told me — you won't have to
+repeat anything. They'll reach out by {{time}}. — {{agent}}
+```
+
+### 9. Feature-request decline (say no without a dead end)
+
+```text
+Hi {{first_name}} — {{feature_idea}} isn't on the roadmap right now, and I want
+to be straight with you rather than string you along. I've logged it for the
+product team ({{tracking_id}}). The closest thing available today is
+{{nearest_alternative}}. — {{agent}}
+```
+
+Never "unfortunately there's nothing we can do" — always offer the nearest path.
+
+### 10. Gentle close (no reply after a follow-up)
+
+```text
+Hi {{first_name}} — I haven't heard back, so I'll close this for now. If
+{{problem}} is still happening, just reply and it reopens right where we left
+off — no need to start over. — {{agent}}
+```
+
+## Full SLA matrix by channel
+
+First-response targets shift by channel: live channels (chat/phone) set a faster
+expectation than async (email). Resolution targets stay constant by priority.
+
+| Priority | Email FRT | Chat FRT | Phone FRT | Resolution |
+|---|---|---|---|---|
+| P1 critical | 30 min | 5–10 min | immediate | ASAP; status update every 30–60 min |
+| P2 high | 1–2 h | 15 min | 5 min | same business day |
+| P3 medium | 4–8 h | 30 min | 10 min | 1–2 business days |
+| P4 low | ~1 business day | 1 h | n/a | best effort |
+
+Keep to 3–4 tiers. Acknowledge inside the FRT window even when the fix will take
+longer — the acknowledgment is the SLA you cannot miss.
+
+## Escalation matrix
+
+| Trigger | Goes to | Owner | What must travel |
+|---|---|---|---|
+| Production outage / data loss | T3 engineering | on-call eng + support lead | full handoff packet + status-page link |
+| "cancel / refund / lawyer / chargeback" | T2 + account owner | account owner | packet + sentiment flag |
+| Enterprise / VIP account | T2 specialist | named CSM | packet + contract context |
+| SLA about to blow | T2 | shift lead | packet + remaining-time |
+| Policy/price claim, unverifiable | T2 | support lead | packet + the exact unanswered question |
+| Assisted/AI draft <85% confidence | human T1 | any human agent | packet + the draft + the uncertainty |
+
+## Handoff packet template
+
+Fill every field. A bare ticket link forces the customer to repeat themselves
+(+90–180s, and it reads as "nobody read my ticket").
+
+```text
+HANDOFF PACKET
+- Customer + account tier:  {{name}} — {{tier}}
+- Ticket / priority:        #{{id}} — {{priority}}
+- One-line summary:         {{what_is_wrong_in_one_line}}
+- Steps already tried:      {{what_you_ruled_out_or_attempted}}
+- Customer sentiment:       {{calm | frustrated | angry | churn-risk}}
+- Collected variables:      {{key=value pairs: plan, timestamps, region, IDs}}
+- What I need from you:      {{the_specific_question_or_action}}
+```

package/skills/dashboard/SKILL.md

@@ -0,0 +1,185 @@
+---
+name: dashboard
+description: "Use when building or fixing a KPI dashboard decision-makers must read in one screen: which metrics earn a tile, how each tile is framed to answer a decision, and which chart fits it. NOT defining the metrics or their targets (that is kpi-framework), wiring the data (that is analytics), or writing a narrative status report (that is reporting)."
+tags: [kpi-dashboard, data-visualization, executive-dashboard, chart-selection, dashboard-design, at-a-glance]
+recommends: [kpi-framework, analytics, reporting, forecasting, business-intelligence, ab-testing, design, spreadsheet-ops]
+origin: risco
+---
+
+# dashboard
+
+A dashboard is read in **5 seconds by someone who will not scroll**. If a busy reader cannot grasp business status that fast, the design failed — no matter how accurate the numbers are. Your job here is **arrangement, framing, and chart choice**, producing a checkable artifact:
+
+- `dashboard.yaml` — a tile manifest (each tile: metric, chart, comparison, owner, refresh, decision).
+- a one-screen layout sketch placing the north-star top-left.
+
+You do **not** decide which metrics matter (that is [kpi-framework](../kpi-framework/SKILL.md)) and you do **not** wire the data source (that is [analytics](../analytics/SKILL.md)). You take a metric set that already exists and make it readable at a glance.
+
+Run `scripts/verify.sh dashboard.yaml` before you hand off. It checks shape and discipline — tile count 1-9, exactly one `north_star: true`, the required keys on every tile, no banned charts — never whether the numbers are correct.
+
+## The Decision Test gate
+
+No tile exists until its metric names the **action it drives**. Ask: *what does someone do differently based on this number?* If the answer is vague ("good to know", "shows we're growing"), the metric is vanity — cut it or convert it. A tile that changes no decision is decoration.
+
+| Vanity metric (Bad) | Actionable conversion (Good) | Decision it drives |
+| --- | --- | --- |
+| Total followers | Follower-growth rate WoW | Double down or change content cadence |
+| Total page views | Conversion rate by source | Reallocate spend to the converting channel |
+| Cumulative signups | Activation rate (signup → key action) | Fix onboarding if activation drops |
+| Total revenue (all-time) | MRR + net revenue retention | Whether to hire / extend runway |
+| App downloads | 7-day retention | Kill or scale the acquisition channel |
+
+Rule: an always-up counter ("total X") is almost always vanity. Convert it to a **rate or ratio** that can go down. Why: a number that only ever rises never triggers an action.
+
+## Tile budget: 5-9, exactly one north-star
+
+Executive dashboards carry roughly **5 to 9 KPIs**. Human working memory caps near ~7 items; more tiles cause analysis paralysis and the screen stops being a glance.
+
+- Exactly **one** tile flagged `north_star: true`. Why: a glance needs a single first read.
+- 4-8 supporting tiles around it. Total ≤ 9.
+
+When a stakeholder demands 20 metrics, do not cram them — **tier**:
+
+- [ ] Does this metric drive a decision the leadership team makes weekly? → main screen.
+- [ ] Is it a diagnostic you only check *after* a main tile turns red? → drill-down view, linked from the parent tile.
+- [ ] Is it commentary / context that needs prose? → route to [reporting](../reporting/SKILL.md), not a tile.
+- [ ] Is it a projection of a metric forward? → [forecasting](../forecasting/SKILL.md), not the live screen.
+- [ ] Does the user want to slice it freely by dimension? → [business-intelligence](../business-intelligence/SKILL.md), not a fixed tile.
+
+## Framing every tile
+
+The minimum viable tile is **not** a number. It is a number plus the context that makes it actionable:
+
+```text
+value + comparison(target | prior | benchmark) + delta + units + date range
++ RYG status + owner + refresh cadence
+```
+
+Bad → Good:
+
+```text
+Bad:   Churn: 4.1%
+Good:  Monthly logo churn — 4.1%  ▲0.6pp vs prior month  (target ≤3.0%)  🔴
+       Owner: Head of CS · Refresh: daily · Range: May 2026
+```
+
+Why each field earns its place:
+
+- **comparison** — a number alone has no "is this good?"; target/prior/benchmark supplies it.
+- **delta** — direction and magnitude of change is the second thing the eye wants.
+- **units + date range** — "4.1%" of what, over what window; ambiguity kills trust.
+- **RYG status** — lets the reader triage in the 5-second glance without reading the number.
+- **owner** — every red tile needs an accountable human, or nothing happens.
+- **refresh cadence** — tells the reader how stale the number can be; a "real-time" label on a weekly metric is a lie.
+
+## Chart per metric: pick by shape
+
+Choose the chart from the **shape of the question**, not from what looks impressive. Full matrix and edge cases in `references/chart-selection.md`.
+
+| Metric shape | Chart | Why |
+| --- | --- | --- |
+| Single headline number | Big-number tile + delta | Fastest read; the north-star usually lives here |
+| Trend over time | Line | Slope shows direction instantly |
+| Category comparison | Sorted horizontal bar | Length is easy to compare; sorting answers "who's worst" |
+| Target vs actual | **Bullet chart** | Compact, comparable; replaces gauges/dials |
+| Part-to-whole (≤5 parts) | Stacked bar or treemap | Pie only legible to 3-5 slices |
+| Correlation | Scatter | Shows relationship between two measures |
+| Distribution | Histogram | Shape of spread, not just average |
+
+Kill-list: no `pie` beyond 5 categories (sorted bar instead) and no `gauge` / `dial` (bullet chart instead) — verify.sh rejects both; no dual-axis, which invents correlations that aren't there; no 3D and no donut-with-center-number gimmicks.
+
+## Layout & data-ink
+
+Lay tiles out for the **Z / F scan pattern**: the eye starts top-left, sweeps right, drops down. Put the north-star top-left; group related KPIs together (acquisition cluster, revenue cluster, health cluster).
+
+Apply the **data-ink ratio**: if a pixel shows no new information, remove it. Strip heavy borders, drop shadows, gradients, 3D, background textures — they raise cognitive load without adding meaning.
+
+**Color is meaning, not decoration.** Use a status palette (red/yellow/green) only for status. A rainbow of tile colors with no semantic meaning makes the screen harder, not friendlier.
+
+```text
+Before:  9 boxed-and-shadowed tiles, each a different bright color,
+         3 pie charts, two gauges, no clear starting point.
+After:   north-star top-left (big number + sparkline);
+         flat tiles, hairline separators, neutral palette;
+         RYG reserved for status; bullets replace gauges;
+         sorted bar replaces the pies.
+```
+
+## The artifact: `dashboard.yaml`
+
+Emit a manifest a BI tool, a web app, or a human can build from. Short schema here; full field reference in `references/tile-schema.md`.
+
+```yaml
+# dashboard.yaml — one screen, one north-star
+title: SaaS Exec Dashboard
+date_range: "2026-05"
+tiles:
+  - id: waa
+    north_star: true
+    metric: Weekly Active Accounts
+    chart: big_number          # + sparkline trend
+    value_source: warehouse.fct_active_accounts
+    units: accounts
+    comparison: { type: target, value: 1200 }
+    delta: vs_prior_week
+    status_logic: "green ≥ target; yellow ≥ 90%; red < 90%"
+    owner: VP Product
+    refresh: daily
+    decision: "If below 90% of target two weeks running, escalate activation work."
+  - id: nrr
+    metric: Net Revenue Retention
+    chart: big_number
+    comparison: { type: benchmark, value: 110 }   # %
+    units: percent
+    owner: VP Sales
+    refresh: monthly
+    decision: "Below 100% triggers a save/expansion review."
+  - id: churn
+    metric: Monthly Logo Churn
+    chart: line
+    comparison: { type: target, value: 3.0 }
+    units: percent
+    owner: Head of CS
+    refresh: daily
+    decision: "Above target investigates cohort + reason codes."
+  - id: runway
+    metric: Cash Runway
+    chart: bullet                      # actual vs target months
+    comparison: { type: target, value: 18 }
+    units: months
+    owner: CFO
+    refresh: monthly
+    decision: "Under 12 months opens fundraise / cost review."
+  - id: pipeline
+    metric: New Pipeline by Source
+    chart: sorted_bar
+    comparison: { type: prior, value: last_month }
+    units: currency
+    owner: Head of Marketing
+    refresh: weekly
+    decision: "Shift spend toward the top-converting source."
+layout:
+  north_star: top_left
+  scan: Z
+  groups: [growth, revenue, health]
+```
+
+The keys verify.sh requires on every tile: `metric`, `chart`, `comparison`, `owner`, `refresh`, `decision`.
+
+## Anti-patterns
+
+| Anti-pattern | Why it fails | Do instead |
+| --- | --- | --- |
+| 20 tiles on one screen | Past ~7, no one can read it in 5 seconds | Cut to 5-9; tier the rest to a drill-down |
+| Vanity metrics (totals, followers) | Never trigger an action | Apply the Decision Test; convert to rates |
+| Bare numbers, no comparison | No "is this good?" signal | Add target / prior / benchmark + delta |
+| Pie chart with 8 slices | Slices become unreadable | Sorted horizontal bar |
+| Gauges and dials | Waste space, resist comparison | Bullet chart |
+| Rainbow tile colors | Color reads as meaning when it isn't | Neutral tiles; RYG for status only |
+| "Real-time" on everything | False precision; refresh-cost theater | Match refresh to decision cadence |
+| It's actually a report | Prose + commentary isn't a glance | Move narrative to reporting |
+| No north-star | Reader has no entry point | One `north_star: true` tile, top-left |
+
+## Handoff
+
+Beyond the routes named above: reading out an experiment or variant significance → [ab-testing](../ab-testing/SKILL.md); visual polish, spacing and type scale of the rendered screen → [design](../design/SKILL.md); pulling or joining the underlying numbers in a sheet → [spreadsheet-ops](../spreadsheet-ops/SKILL.md).