rsc-universal 0.1.1

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,205 @@
+---
+name: dashboard
+description: "Use when building or fixing a KPI dashboard that decision-makers will actually open and act on within one screen — arranging which metrics earn a tile, framing each tile so it answers a decision at a glance, and picking the right chart per metric. Triggers: 'build a KPI dashboard for leadership', 'exec dashboard on one screen', 'nobody opens the dashboard we built', '20 tiles and I still can't tell if the business is healthy', 'which chart for each of these metrics', 'munta un dashboard de KPIs per a direcció amb el north-star a dalt', 'el dashboard tiene demasiados gráficos y nadie lo mira'. 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 budget, one north-star, required keys, banned charts) — never whether the numbers are correct.
+
+## The one rule: the 5-second read
+
+A dashboard is a **glance, not a report**. The reader looks at the top-left, gets the headline, and decides whether anything needs their attention. Everything you do serves that.
+
+- One north-star tile, read first, top-left. Why: a screen with no clear entry point forces the reader to hunt, and they won't.
+- If a tile does not change a decision, it is decoration. Cut it (Decision Test below).
+- A bare number is not actionable. Every number carries a comparison.
+
+## 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.
+
+| 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 (verify.sh enforces the first two):
+
+- No `pie` beyond 5 categories — slices become unreadable. Use a sorted bar.
+- No `gauge` / `dial` — they waste space and resist comparison. Use a **bullet chart**.
+- No dual-axis trickery — two y-axes invent correlations that aren't there.
+- No 3D, 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]
+```
+
+verify.sh parses this, counts tiles (must be 1-9), checks exactly one `north_star: true`, requires `metric/chart/comparison/owner/refresh/decision` on every tile, and rejects banned charts.
+
+## 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
+
+- Metrics undefined? Define the north-star, metric tree, targets and owners first → [kpi-framework](../kpi-framework/SKILL.md).
+- No data behind the tiles? Instrument events, funnels, attribution → [analytics](../analytics/SKILL.md).
+- Need a written status with commentary on *why* a number moved → [reporting](../reporting/SKILL.md).
+- Projecting a metric forward under scenarios → [forecasting](../forecasting/SKILL.md).
+- Self-serve slice-and-dice / semantic layer → [business-intelligence](../business-intelligence/SKILL.md).
+- Reading out an experiment / variant significance → [ab-testing](../ab-testing/SKILL.md).
+- Visual polish, spacing, type scale of the rendered screen → [design](../design/SKILL.md).
+- Pulling/joining the underlying numbers in a sheet → [spreadsheet-ops](../spreadsheet-ops/SKILL.md).

package/skills/dashboard/evals/README.md

@@ -0,0 +1,3 @@
+# Evals — dashboard
+
+`cases.yaml` is a human/LLM-graded trigger and capability set, not an auto-runner. To use it: read each `should_trigger` prompt and confirm an agent routing skills would reach into `dashboard`, then read each `should_not_trigger` prompt and confirm it routes to the named sibling instead (the boundary against `kpi-framework`, `analytics`, `reporting`, `forecasting`, `business-intelligence`, and `ab-testing`) — eyeball the routing, don't just trust the labels. For the `capability` case, have the agent actually produce a `dashboard.yaml` from the 14-metric scenario, then grade the output against the `must_include` rubric and run `scripts/verify.sh path/to/dashboard.yaml`; a real pass means the rubric items are all present AND verify.sh exits 0. verify.sh needs `python3` with PyYAML and is read-only, so it is safe to run on any candidate artifact.

package/skills/dashboard/evals/cases.yaml

@@ -0,0 +1,50 @@
+skill: dashboard
+
+should_trigger:
+  - prompt: "Build a KPI dashboard for our leadership team that fits on one screen."
+    why: Core build job — arrange a metric set into a scannable one-screen layout.
+  - prompt: "Nobody opens the dashboard we built — it has too many charts and you can't tell if we're healthy."
+    why: Non-obvious audit/fix symptom; the tile-budget + 5-second-read failure mode this skill owns.
+  - prompt: "Which chart should each of these 8 metrics use? Some are trends, some are target-vs-actual."
+    why: Chart-per-metric selection is a core capability (line vs bullet vs sorted bar).
+  - prompt: "Munta un dashboard de KPIs per a direcció amb el north-star a dalt."
+    why: Catalan phrasing for the build job, including the north-star placement rule.
+  - prompt: "El dashboard tiene 20 gráficos y nadie lo mira — recórtalo a lo que de verdad importa."
+    why: Spanish phrasing; tile-budget + Decision Test (cutting vanity tiles).
+  - prompt: "Turn this list of metrics into a tiered, scannable layout with one north-star tile."
+    why: Layout hierarchy / Z-F scan with a single entry point.
+  - prompt: "Give me a dashboard.yaml manifest a developer can render for our exec metrics."
+    why: Producing the checkable artifact (tile manifest) is the literal output of this skill.
+
+should_not_trigger:
+  - prompt: "Decide our north-star metric and build the metric tree with targets and owners."
+    route_to: kpi-framework
+    why: Defining which metrics matter and their targets — dashboard displays a metric set, it does not choose it.
+  - prompt: "Set up event tracking and funnels in PostHog so we can measure activation."
+    route_to: analytics
+    why: Instrumentation and data production — analytics produces the numbers the dashboard arranges.
+  - prompt: "Write the monthly board report with commentary on why churn rose."
+    route_to: reporting
+    why: A narrative document with prose, not a live at-a-glance screen.
+  - prompt: "Project our MRR for the next 4 quarters under three scenarios."
+    route_to: forecasting
+    why: Predicting a metric forward, not displaying current status.
+  - prompt: "Build a self-serve BI semantic layer so anyone can slice revenue by any dimension."
+    route_to: business-intelligence
+    why: Exploration / semantic modeling platform, not a fixed at-a-glance screen.
+  - prompt: "Read out our pricing A/B test — is variant B's lift significant?"
+    route_to: ab-testing
+    why: Experiment readout / variant significance, not dashboard layout.
+
+capability:
+  - scenario: >
+      Given a raw list of 14 candidate metrics for a SaaS exec team — including vanity
+      ones like total signups, total page views, and total followers — produce a
+      dashboard.yaml manifest plus a one-screen layout.
+    must_include:
+      - Applies the Decision Test and cuts or converts vanity metrics (total signups → activation rate; page views → conversion rate by source; total followers → follower-growth rate).
+      - Final manifest has 5-9 tiles with exactly one tile flagged north_star true.
+      - Every tile carries a comparison (target | prior | benchmark), an owner, a refresh cadence, and a non-empty decision field.
+      - Correct chart per metric shape (trend → line, target-vs-actual → bullet, category comparison → sorted bar, headline → big_number); no pie >5 slices and no gauge/dial.
+      - A layout block placing the north-star top-left with a Z or F scan and grouped tiles.
+      - Valid YAML that passes scripts/verify.sh (parses, budget, one north-star, required keys, no banned charts).

package/skills/dashboard/references/chart-selection.md

@@ -0,0 +1,34 @@
+# Chart selection — full matrix and edge cases
+
+Pick the chart from the **shape of the question the metric answers**, not from novelty. The body table covers the common cases; this is the full matrix plus the situations where the obvious choice is wrong.
+
+## Full metric-shape → chart matrix
+
+| Metric shape | Primary chart | Acceptable alternative | Avoid |
+| --- | --- | --- | --- |
+| One headline number, "where are we now" | Big-number tile + delta | Big number + sparkline | Gauge, dial |
+| Value over time, "which way is it going" | Line | Area (only if part-to-whole over time) | Many overlapping lines (>4) |
+| Compare a category across items | Sorted horizontal bar | Dot plot | Pie, vertical bars with long labels |
+| Actual vs a single target | Bullet chart | Bar with a target reference line | Gauge, dial, donut |
+| Part-to-whole, ≤5 parts | Stacked bar | Treemap, pie (3-5 slices only) | Pie >5, nested donuts |
+| Part-to-whole over time | 100% stacked area/bar | Small multiples of stacked bars | 3D area |
+| Relationship between two measures | Scatter | Bubble (adds a 3rd measure via size) | Dual-axis line |
+| Distribution of a measure | Histogram | Box plot | Single average number alone |
+| Progress toward a deadline/goal | Bullet or progress bar | Burn-up line | Gauge |
+| Geographic spread | Choropleth map | Sorted bar by region | 3D map, bubble-on-map clutter |
+
+## Edge cases where the obvious chart is wrong
+
+- **Sparkline inside a tile.** A north-star big number reads better with a tiny inline trend than with a separate chart tile. Use a sparkline when the *value* is the message and the *trend* is supporting context.
+- **Small multiples beat one busy chart.** Comparing the same trend across 6 segments? Don't stack 6 lines on one axis — render 6 small identical line charts in a grid. The eye compares shapes faster than it untangles a spaghetti chart.
+- **When a plain table beats every chart.** If the reader needs to look up exact values, compare more than ~3 precise numbers per row, or the data is inherently tabular (a ranked leaderboard with several columns), a clean table with right-aligned numbers and inline RYG cells wins. A chart that forces the reader back to a tooltip for the real number has failed.
+- **Log scale.** Use only when values span orders of magnitude (e.g. error counts from 1 to 100,000) AND the audience understands log axes. For an exec dashboard, prefer splitting the metric or using a different view — a log axis silently understates big swings to a non-technical reader.
+- **Annotating inflection points.** A trend line earns a one-line annotation at the moment something changed ("v2 launch", "price increase"). Why: the reader's first question at any bend is "what happened here"; answer it on the chart, not in a footnote.
+- **Sorted bars for "who missed target".** When the question is accountability ("which regions are below plan"), sort bars by gap-to-target and color the misses. Don't sort alphabetically — sorting *is* the answer.
+- **Dual axis: almost never.** Two y-axes on one chart invent correlations by letting you scale each line to "look related". If two metrics must be compared, normalize both to an index (base 100) and plot on one axis, or use two stacked charts.
+
+## Color discipline
+
+- Reserve red/yellow/green strictly for **status**. If everything is colored, nothing signals.
+- Use a single neutral hue for non-status series; differentiate by position and labels, not by a rainbow.
+- Ensure status is not encoded by color alone — pair RYG with an icon or shape so the screen stays readable for color-blind viewers (visual polish lives in [design](../../design/SKILL.md)).

package/skills/dashboard/references/tile-schema.md

@@ -0,0 +1,164 @@
+# Tile schema — `dashboard.yaml` field reference
+
+The artifact `dashboard.yaml` is a manifest a BI tool, a web app, or a human can render. This is the full field-by-field reference, two filled examples, and exactly what `scripts/verify.sh` enforces.
+
+## Top-level keys
+
+| Key | Required | Type | Notes |
+| --- | --- | --- | --- |
+| `title` | yes | string | Dashboard name shown to the reader |
+| `date_range` | yes | string | Active window, e.g. `"2026-05"` or `"last 90d"` |
+| `tiles` | yes | list | 1-9 entries (budget rule; verify.sh fails >9) |
+| `layout` | yes | map | Placement + scan pattern (below) |
+
+## Tile fields
+
+| Field | Required | Type | Notes |
+| --- | --- | --- | --- |
+| `id` | yes | string | Unique slug, referenced by drill-downs |
+| `north_star` | one tile only | bool | Exactly one tile sets `true`; verify.sh enforces |
+| `metric` | yes | string | Human label of the KPI |
+| `chart` | yes | enum | `big_number`, `line`, `sorted_bar`, `bullet`, `stacked_bar`, `treemap`, `scatter`, `histogram`. Banned: `pie` >5 cats, `gauge`, `dial` |
+| `value_source` | recommended | string | Where the number comes from (table/query/sheet) — analytics owns this |
+| `units` | recommended | enum/string | `percent`, `currency`, `count`, `months`, etc. |
+| `comparison` | yes | map | `{ type: target\|prior\|benchmark, value: <n or ref> }` |
+| `delta` | recommended | string | What the change is measured against, e.g. `vs_prior_week` |
+| `status_logic` | recommended | string | The RYG rule, e.g. `"green ≥ target; yellow ≥ 90%; red < 90%"` |
+| `owner` | yes | string | Accountable human/role |
+| `refresh` | yes | enum | `realtime`, `hourly`, `daily`, `weekly`, `monthly` — match to decision cadence |
+| `decision` | yes | string | The Decision Test answer: what action this number drives. Must be non-empty |
+
+## `layout` block
+
+| Field | Type | Notes |
+| --- | --- | --- |
+| `north_star` | enum | `top_left` (recommended) — where the entry-point tile sits |
+| `scan` | enum | `Z` or `F` reading pattern |
+| `groups` | list | Named clusters of related tiles, e.g. `[growth, revenue, health]` |
+
+## Example A — SaaS exec (the body's worked example, extended)
+
+```yaml
+title: SaaS Exec Dashboard
+date_range: "2026-05"
+tiles:
+  - id: waa
+    north_star: true
+    metric: Weekly Active Accounts
+    chart: big_number
+    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: "Below 90% of target two weeks running escalates activation work."
+  - id: nrr
+    metric: Net Revenue Retention
+    chart: big_number
+    units: percent
+    comparison: { type: benchmark, value: 110 }
+    owner: VP Sales
+    refresh: monthly
+    decision: "Below 100% triggers a save/expansion review."
+  - id: churn
+    metric: Monthly Logo Churn
+    chart: line
+    units: percent
+    comparison: { type: target, value: 3.0 }
+    owner: Head of CS
+    refresh: daily
+    decision: "Above target investigates cohort + reason codes."
+  - id: runway
+    metric: Cash Runway
+    chart: bullet
+    units: months
+    comparison: { type: target, value: 18 }
+    owner: CFO
+    refresh: monthly
+    decision: "Under 12 months opens fundraise / cost review."
+  - id: pipeline
+    metric: New Pipeline by Source
+    chart: sorted_bar
+    units: currency
+    comparison: { type: prior, value: last_month }
+    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]
+```
+
+## Example B — E-commerce ops
+
+```yaml
+title: E-commerce Ops Dashboard
+date_range: "last 28d"
+tiles:
+  - id: rev
+    north_star: true
+    metric: Net Revenue
+    chart: big_number
+    units: currency
+    comparison: { type: prior, value: prev_28d }
+    delta: vs_prior_period
+    status_logic: "green ≥ prior; yellow within -5%; red < -5%"
+    owner: Head of Ecom
+    refresh: daily
+    decision: "A red week triggers a promo / merchandising review."
+  - id: cvr
+    metric: Conversion Rate by Channel
+    chart: sorted_bar
+    units: percent
+    comparison: { type: benchmark, value: 2.5 }
+    owner: Growth Lead
+    refresh: daily
+    decision: "Reallocate ad spend toward channels above benchmark."
+  - id: aov
+    metric: Average Order Value
+    chart: line
+    units: currency
+    comparison: { type: prior, value: prev_28d }
+    owner: Merchandising
+    refresh: daily
+    decision: "Falling AOV prompts a bundle / upsell test."
+  - id: cac
+    metric: CAC vs Target
+    chart: bullet
+    units: currency
+    comparison: { type: target, value: 35 }
+    owner: Growth Lead
+    refresh: weekly
+    decision: "Over target pauses the worst-performing campaign."
+  - id: returns
+    metric: Return Rate
+    chart: line
+    units: percent
+    comparison: { type: target, value: 8.0 }
+    owner: Ops Manager
+    refresh: weekly
+    decision: "A rising trend opens a sizing/quality investigation."
+layout:
+  north_star: top_left
+  scan: F
+  groups: [acquisition, revenue, fulfillment]
+```
+
+## What `verify.sh` enforces (and what it does not)
+
+Enforces — **shape and discipline**:
+
+1. File parses as YAML.
+2. `tiles:` exists and holds 1-9 entries (fails if >9 — the budget rule).
+3. Exactly one tile has `north_star: true`.
+4. Every tile has non-empty `metric`, `chart`, `comparison`, `owner`, `refresh`, `decision`.
+5. No `chart: pie` with more than 5 categories; no `chart: gauge` or `chart: dial`.
+
+Does **not** judge:
+
+- Whether the chosen metrics are the *right* metrics — that is [kpi-framework](../../kpi-framework/SKILL.md).
+- Whether the numbers/values are correct — that is the data layer ([analytics](../../analytics/SKILL.md)).
+
+So a `dashboard.yaml` can pass verify.sh and still display the wrong metrics. verify.sh guards the craft of the dashboard, not the choice of what to measure.