Monthly Quality Review Deck

# Monthly Quality Review Deck

Builds a recurring monthly quality-review deck for a support/CX/sales team, sourcing data from the **Rippit MCP**. Building this deck well takes more than a template — it takes a specific way of pulling and verifying data from Rippit so the numbers hold up when a reviewer clicks through to the source.

**Read `references/pitfalls.md` before building anything** — it captures population-scope bugs, fabricated quotes, and denominator mistakes that only surface when someone checks the deck against the source system.

## First run — make it yours

Before pulling any data, interview the user one question at a time, in plain quality-review language, then restate the filled-in bindings for confirmation before running. On later runs, reuse these bindings unless the user asks to change them.

1. **{{team_population}}** — "Which team or group are we reviewing, and how is it defined in your data — which groups, ticket forms, and channels count as this team?" (This is the population filter every number on the deck is scoped to.)
2. **{{review_month}}** — "Which month should this quality review deck cover?" (Sets the date range for all pulls.)
3. **{{contact_themes}}** — "Which contact themes or categories should get their own slide?" (Drives the per-theme slide list.)
4. **{{top_question}}** — "What's the top question or deep-dive topic of the month you want extra slides for?" (Drives the deep-dive slides.)
5. **{{brand_spec}}** — "Do you have a brand spec (colors, fonts, logo), or should I use a clean default?" (Applied to every slide; reuse for future months.)

## What you need before starting

1. **Rippit MCP connected** (`Rippit MCP:*` tools available). If not, tell the user and stop.
2. **The pptx skill** (`/mnt/skills/public/pptx/SKILL.md`) — read it before writing any pptxgenjs code, every time.
3. A defined population for {{team_population}} — the exact group/ticket-form/channel filter — and the {{review_month}} date range.

## Workflow

### Step 1 — Scope the population explicitly, before pulling any numbers
Write down the exact filter for {{team_population}} and {{review_month}}: which group value(s), which ticket-form value(s) if relevant, which date range, which channels. State it as a sentence to yourself. This prevents silently mixing two different populations. See `references/pitfalls.md` §1.

### Step 2 — Pull the core month-in-review numbers
Use `Rippit MCP:describe_table` on the core ticket table to see what enrichment columns already exist — don't assume, check. Then `aggregate_table` (groupBy theme/category, count) to get total contact volume, resolution rate, sentiment breakdown, and volume by contact theme.

### Step 3 — For each theme in {{contact_themes}}, get three layers
1. **Sub-driver breakdown** — why people contact about this theme.
2. **Sentiment / pain-point breakdown** — of the negative-sentiment subset, what's driving frustration (usually a fresh enrichment).
3. **Real quotes with ticket numbers** — never write a quote from memory or paraphrase a reason field as verbatim. See `references/pitfalls.md` §3.

### Step 4 — Build enrichments when the breakdown doesn't exist
```
1. Rippit MCP:create_worksheet   — scope to exactly the rows you need
2. Rippit MCP:enrich_worksheet   — 1-3 new columns: a category enum (4-8 values, with an explicit "not applicable"/"other" bucket) + optionally a verbatim-quote column
3. Rippit MCP:get_enrich_status  — poll until done:true
4. Rippit MCP:aggregate_table    — groupBy the new category column, count
5. Rippit MCP:read_table         — pull real rows with quotes for "In Their Words" cards
```
**Writing good enrichment instructions:** give concrete example labels; always include an explicit "not applicable"/"other" bucket; split plausibly overlapping concepts into two enum columns; for quote columns specify exact words only, no paraphrasing, one sentence, and what to return when there's no clear quote. See `references/rippit_patterns.md`.

### Step 5 — Verify before building a single slide
Run `references/pitfalls.md` as a checklist: does every percentage's denominator match its slide label? Did you exclude categories that don't belong in the population? Are all quotes real and ticket-traceable? Do slides sharing a number agree?

### Step 6 — Build the deck
Use `scripts/build_deck_template.js` as your starting point (reusable layout functions). Apply {{brand_spec}}. Standard skeleton: Title; Month in Review; one slide per theme in {{contact_themes}}; deep-dive slide(s) for {{top_question}}; Quality scorecard; Trends & Flags; Recommended Actions. Build iteratively — render, check, move on.

### Step 7 — QA before presenting
1. `python /mnt/skills/public/pptx/scripts/office/validate.py <file>.pptx`
2. Render to images and actually look at every slide — insertions shift footers and can overlap untouched slides.
3. `markitdown` the deck and grep for placeholder text (`TODO`, `[insert`, `xxx`, `lorem`).
4. Re-check cross-slide numbers still agree after edits.

### Step 8 — Iterate
Treat follow-up questions as verification requests: re-derive the number from source, show your work, then update the slide.

## Reference files
- **`references/pitfalls.md`** — read first, every time.
- **`references/rippit_patterns.md`** — enrichment instruction templates and query shapes.
- **`scripts/build_deck_template.js`** — reusable pptxgenjs layout library; copy, don't edit in place.