broccolini-bot/docs/superpowers/specs/2026-06-04-per-staff-metrics-design.md

# Per-Staff Metrics & Ticket Analytics — Design

**Date:** 2026-06-04
**Status:** Approved (design); implementation pending
**Component:** broccolini-bot

## Goal

Capture per-staff and per-ticket activity as a durable, event-sourced log, and
expose a useful subset via a `/stats` command. The event log is the foundation
for a future analytics dashboard on the tickets website (graphs, timing
analyses, busiest-time heatmaps, per-game and per-emailer reporting).
**Principle: collect rich data now** (history cannot be backfilled); `/stats` v1
surfaces the count metrics; timing/temporal metrics are collected but displayed
on the website later.

Because it is event-sourced, interpretation questions (does a reopen revoke
resolution credit? does time-open reset?) do **not** need a single baked-in
answer — events are recorded with timestamps and the query layer decides.

## Metrics

### Counts (shown in `/stats` v1, per staff member)
- **Claims**; **claims while escalated, by tier** (`claim` events with `tier > 0`)
- **Closes** performed by the staff member
- **Resolved (credit)** — closes where the staff member was the **claimer**
- **Escalations** / **De-escalations**, by tier
- **Unclaimed-at-close** — closes where the ticket had no claimer
- **Transfers** (initiated / received); **Reopens** (rate)
- Every count sliceable **email vs discord** and by **priority**

### Ticket volume & temporal (derived from `Ticket` collection)
- Total tickets, **email vs discord**, over a window.
- **Busiest times** — distribution of `createdAt` by hour-of-day and day-of-week
  (and `closedAt` similarly). Stored as full UTC datetimes; website buckets/TZ-adjusts.

### Timing (collected now; website-only display in v1)
Derived from event timestamps + `ticket.createdAt` / `closedAt`:
- time to first staff response; time to claim; time open (created → closed)
- time to escalation; time to first response & to claim after escalation
- time to close after escalation; total time open across reopen cycles

## Ticket source & tier

- **Source:** `discord` if `gmailThreadId` starts with `discord-`/`discord-msg-`, else `email`. Denormalized as `ticketType` on every event.
- **Requester:** email tickets are attributed to `senderEmail`; discord tickets to the creator's `creatorId`. Both denormalized onto events so per-emailer (email) and per-user (discord) reporting work, sliceable by source.
- **Tier** (existing convention): `0` normal, `1` → "Tier 2 Support", `2` → "Tier 3 Support". Events store raw numeric `tier`; `/stats` mirrors the labels.

## Data model

### New model `StaffAction` (event log, in `models.js`)

```
{
  staffId:       String,   // actor's Discord user ID ('system' for automated)
  type:          String,   // 'claim'|'response'|'escalate'|'deescalate'|'close'|'reopen'|'transfer'
  tier:          Number,   // ticket escalationTier at the moment (0 if none)
  ticketType:    String,   // 'email' | 'discord'
  priority:      String,   // ticket priority at the moment
  game:          String,   // detected game (denormalized)
  senderEmail:   String,   // requester for EMAIL tickets (denormalized)
  creatorId:     String,   // requester for DISCORD tickets — creator's user ID (denormalized)
  gmailThreadId: String,   // ticket linkage / per-ticket timeline join key
  guildId:       String,
  createdAt:     Date,      // default: Date.now (function reference)

  // close-only:
  closerType:    String,   // 'staff' | 'user' | 'system'
  resolverId:    String,   // ticket.claimerId at close (credit); null if unclaimed
  wasClaimed:    Boolean,   // false → unclaimed-at-close

  // transfer-only:
  fromId:        String,    // previous claimer
  toId:          String     // new claimer
}
```

For `close`, `staffId` = the closer, `resolverId` = the claimer credited.
For `transfer`, `staffId` = who ran `/transfer`.
For `reopen`, `staffId` = `'system'` (customer email reply re-opens the thread).

Indexes: `{ staffId: 1, createdAt: -1 }` and `{ gmailThreadId: 1, createdAt: 1 }`.

### `Ticket` schema changes
- `game: String` — set at creation from existing `detectGame(subject, rawBody)`.
- `closedAt: Date` — set when a ticket is closed (robust source for time-open /
  busiest-close-times even if events are pruned).

## Recording

New `services/staffStats.js` → `recordAction(staffId, type, payload)`,
fire-and-forget (`.catch(() => {})`), never blocking the action. `ticketType`,
`priority`, `game`, `senderEmail` read from the ticket being acted on.

**Idempotency (correctness requirement):** record an event **only on a successful
state transition** — a claim that actually set the claimer, a close that actually
closed, an escalate that changed tier. No-op / rejected / double-click
interactions must not produce events.

| Event        | Site                                                  | Notes |
|--------------|-------------------------------------------------------|-------|
| `claim`      | `handlers/buttons.js` `handleClaimButton`             | only if claim succeeds; `tier` = current |
| `response`   | `handlers/messages.js` `handleDiscordReply`           | only when author `isStaff`; email & discord; before the email-only early return |
| `escalate`   | `handlers/commands/escalation.js` `runEscalation`     | `tier` = new tier |
| `deescalate` | `handlers/commands/escalation.js` `runDeescalation`   | `tier` = new tier |
| `transfer`   | `handlers/commands/index.js` `handleTransfer`         | `fromId` = old claimer, `toId` = target, actor = runner |
| `close`      | `handlers/buttons.js` `runFinalClose`                 | sets `closerType`/`resolverId`/`wasClaimed`; also set `ticket.closedAt` |
| `close`      | `handlers/commands/close.js` `finalizeForceClose`     | capture closer ID via `pendingCloses` (store `interaction.user.id` at countdown start) |
| `reopen`     | `gmail-poll.js` reopen path (`existing.status === 'closed'`) | `staffId='system'`, customer-driven |

Auto-close (`services/tickets.js`) and orphan-channel reconcile / auto-unclaim
closes → `close` with `closerType: 'system'`, `staffId: 'system'`, preserving
`resolverId`/`wasClaimed` so resolution credit and unclaimed-at-close still count
without attributing a human.

`response` volume: record each staff reply (low volume); "first response" =
`min(createdAt)`; "after escalation" = first `response` after the `escalate` event.

## `/stats` command

Registered in `commands/register.js`; handler in the commands layer.

- `period` — string, **autocomplete + free text**, default **30 days**. Suggestions:
  `7 days`, `30 days`, `3 months`, `6 months`, `1 year`. Parses `<n>d/w/m/mo/y` and
  bare number = days; unparseable → 30 days.
- `member` — optional user.
- `source` — optional choice: **all** (default) / **email** / **discord**. Filters
  every metric by `ticketType`, so the same command shows combined stats or a
  single channel's stats.

Gating: `setDefaultMemberPermissions(ManageMessages)` + `requireStaffRole`,
ephemeral. No `member` → caller's own; `member` set → only if caller ∈
`STATS_ADMIN_IDS`, else "You can only view your own stats."

The command shows the **full** count metric set (not a trimmed subset); `source`
toggles between combined and per-channel views. Aggregation: MongoDB pipeline over
`StaffAction` (+ `Ticket` for volume) filtered by actor, `createdAt >= now - window`,
and optional `ticketType`, grouped by `type`/`tier`/`ticketType`/`priority`.

### Display (embed, v1 — counts)
```
📊 Stats — @member · last 30 days        (email 30 · discord 12)
Claimed: 42        (while escalated — Tier 2: 5 · Tier 3: 1)
Closed: 38         (unclaimed: 4)
Resolved (credited): 35
Escalated:         Tier 2: 4 · Tier 3: 1
De-escalated:      Tier 2: 1 · Tier 3: 0
Transfers: in 2 · out 3       Reopens (their resolved tickets): 1
```
Timing/busiest-times not shown in v1 — collected for the website.

## Configuration
```
STATS_ADMIN_IDS=321754640431710226,691678135527276614,224692549225283584
```
(chicken, broccoli, ketchup) — comma-separated; users allowed to view others' stats.

## Non-goals (v1)
- Tag / Gmail-folder / canned-response usage tracking (dropped).
- Unclaim-action tracking (we track unclaimed-*at-close*).
- Multi-staff leaderboard (per-member view only).
- Website dashboard, graphs, timing/busiest-time displays, per-game/per-emailer
  reports, internal-API stats endpoint. **Deferred** — data captured now.
- SLA / business-hours adjustment of timings (website computes from raw UTC).
- Event-log pruning (volume is low; revisit if needed).

## Verification
- Unit: period parser; aggregation shaping (counts by type/tier/ticketType/priority;
  resolved-credit; unclaimed-at-close; transfer in/out; reopen).
- Unit: idempotency — no event on no-op claim/close.
- Manual: run claim/respond/escalate/deescalate/transfer/close/reopen across a test
  email ticket and a test discord ticket; confirm `StaffAction` docs and fields,
  `ticket.game`/`closedAt`; confirm per-ticket timeline yields timing deltas;
  `/stats` counts + email/discord split; non-admin can't view others, admin can.
  Deploy `docker compose up --build -d`; confirm bot logs ready.
```