Preparação de QBR com Salesforce + Gong + Claude

---
name: qbr-prep
description: Generate a 70%-done QBR draft for a single customer account. Pulls Salesforce account history, Salesforce cases, Gong call themes from the last 90 days, and the success-plan doc, then runs three Claude passes (synthesis, risk + expansion, tone-match) to populate slot-mapped slide content for the team's QBR template.
---

# QBR prep

## When to invoke

When a CSM is opening a fresh QBR deck for a named account and wants a populated draft to edit, not a blank template. Take an account ID, the previous QBR's contents, the current quarter's usage data, and the active success-plan doc as inputs and produce slot-mapped slide content plus a one-page exec summary.

Do NOT invoke this skill for:

- Auto-publishing a QBR deck without CSM review. The skill is a draft engine, not a publisher.
- Customer-facing decks that have not been approved by the named account team. Every QBR goes through the AE/CSM-of-record before the customer sees it.
- Accounts with fewer than 30 days of usage data or no logged Gong calls in the quarter. The skill flags this and refuses rather than padding with generalities.
- Renewal forecasting or churn prediction. Use the churn-risk-summarizer skill for that — its rubric is calibrated for retention scoring, not deck content.

## Inputs

- Required: `account_id` — the Salesforce 18-character account ID
- Required: `quarter` — the QBR quarter label (e.g. `Q1-2026`)
- Required: `last_qbr_path` — local path or Google Drive URL to the previous QBR deck (the skill diffs commitments-then vs reality-now)
- Required: `success_plan_ref` — Notion page ID, Salesforce custom object ID, or Gainsight CTA reference for the active success plan
- Optional: `usage_data_path` — CSV or BigQuery table reference for product usage events. Defaults to the team's standard usage warehouse view if unset.
- Optional: `template_id` — slide template key from `references/qbr-template-slots.md`. Defaults to `standard-quarterly`.
- Optional: `voice_samples` — array of paths to 3 prior QBRs from the same CSM (used by the tone-match pass)

## Reference files

Always read these from `references/` before generating slide content. Without them, the skill's output is generic and the slot mapping will not match the team's actual deck.

- `references/qbr-template-slots.md` — the named placeholder slots in the team's QBR template, with the data shape each slot expects
- `references/success-plan-format.md` — the schema the skill expects for the success-plan doc, plus a fillable template the CSM team adopts
- `references/sample-output.md` — a worked example of populated slot content for a fictional account, used as a tone and structure anchor

## Method

Run these steps in order. Steps 1a-1d run in parallel because they hit independent systems and the bottleneck is API latency, not Claude tokens.

### 1. Parallel data pulls

a. **Salesforce account history.** Pull Account, Opportunity, and Case records for the past 12 months. Compute: ARR trajectory, expansion or contraction events, renewal date, NPS history if captured. Why parallel: Salesforce SOQL is the slowest of the four and gates the rest.

b. **Salesforce cases.** Pull all cases opened in the QBR quarter. Compute: ticket volume vs prior quarter, severity mix, median time-to-resolve, top three case categories.

c. **Gong call themes.** Pull all calls tagged to the account in the past 90 days. Why 90 days: anything older predates the quarter and biases the narrative backward. Surface raw transcripts plus call metadata (attendees, duration, recording URL).

d. **Success-plan doc.** Fetch the success plan referenced by `success_plan_ref`. Parse against the schema in `references/success-plan-format.md`. If the schema does not match, halt and surface the parse error rather than guessing.

If any of 1a-1d returns empty or errors, record `unavailable` for that stream rather than synthesizing. The output template explicitly accommodates missing streams.

### 2. Pass 1 — synthesis

Claude reads all four data streams and the previous QBR. It produces an internal scratchpad: top wins of the quarter, top losses, themes from Gong (what executives said about value, blockers raised, competitors mentioned), and a usage-trend summary keyed to the success-plan goals. Why a dedicated synthesis pass: the next two passes need a single coherent picture, not raw data. Doing synthesis-and-slides in one pass produces uneven slide content because Claude over-weights whichever stream it read last.

### 3. Pass 2 — risks and expansion paths

Claude takes the synthesis scratchpad plus the success plan and produces: open risks with severity (red, yellow, green) and a one-line mitigation per risk; proposed expansion paths ranked by signal strength (usage-led, persona-led, contract-led). Why a separate pass: risks and expansion are the parts a CSM most often edits, so they get focused token budget and explicit reasoning rather than being squeezed alongside slide-writing.

### 4. Pass 3 — tone-match and slot mapping

Claude reads the optional `voice_samples` (or falls back to `references/sample-output.md`) and rewrites the synthesis + risks + expansion content into the team's voice — neutral, data-led, no superlatives. Then it maps the rewritten content to the named slots from `references/qbr-template-slots.md`. Why per-template slot mapping: every team's QBR template differs (some have a "wins" slide, some fold wins into "value delivered"). Mapping at the end means swapping templates does not require rerunning the upstream passes.

### 5. Emit output

Write a single Markdown file with one section per slot. Each section is wrapped in a fenced block tagged with the slot name, so a downstream importer (the deck-assembly script the team runs separately) can split it back out. Also write a one-page exec summary as a separate file for the CSM to skim before opening the deck.

## Output format

````markdown
# QBR draft — {Account name} — {Quarter}

> Generated {YYYY-MM-DD HH:MM}. Status: {complete | partial: missing streams listed below}.
> Missing streams: {gong | success_plan | usage | none}

## Slot: `usage_trend`

```text
{Three-sentence summary of usage trajectory keyed to the prior quarter. Names the metric, the delta, and one likely cause from the synthesis pass.}
```

## Slot: `top_wins`

```text
- {Win 1 — outcome, metric, customer quote if available}
- {Win 2 — outcome, metric, customer quote if available}
- {Win 3 — outcome, metric, customer quote if available}
```

## Slot: `risk_summary`

```text
| Risk | Severity | Mitigation owner | Mitigation |
|---|---|---|---|
| {Risk 1} | red | {CSM | AE | Product} | {one line} |
| {Risk 2} | yellow | ... | ... |
```

## Slot: `success_plan_progress`

```text
| Goal | Target | Actual | Status |
|---|---|---|---|
| {Goal 1} | ... | ... | on-track |
| {Goal 2} | ... | ... | at-risk |
```

If success plan is `unavailable`, this slot emits the literal string `SUCCESS_PLAN_UNAVAILABLE` so the deck-assembly script can blank the slide rather than render stale content.

## Slot: `expansion_paths`

```text
1. **{Path 1}.** Signal: {usage | persona | contract}. Confidence: high | medium | low. Next step: {one sentence}.
2. **{Path 2}.** ...
3. **{Path 3}.** ...
```

## Slot: `exec_summary`

```text
{Five-bullet summary intended for the cover slide. Each bullet is one fact, no adjectives. Always ends with the proposed agenda for the live QBR call.}
```
````

## Watch-outs

- **Usage-data drift.** If the usage warehouse view changes shape (column rename, metric redefinition), the trend summary is silently wrong. Guard: the skill validates the usage CSV header against `references/qbr-template-slots.md` schema and refuses to populate `usage_trend` if columns are missing or renamed. The deck-assembly script then renders the slide blank rather than misleading content.
- **Success-plan staleness.** Success plans that have not been touched in over 60 days produce confident-sounding but stale `success_plan_progress` slots. Guard: the skill checks the success-plan doc's `last_updated` field; if older than 60 days, it prepends a `SUCCESS_PLAN_STALE` flag to that slot so the CSM has to acknowledge before the slide is approved.
- **Tone mismatch with the customer.** Default tone is the CSM team's voice — that may not match how this specific customer is used to being talked to (e.g. an enterprise customer expects more formal phrasing than a startup). Guard: when `voice_samples` are passed, the tone-match pass weights customer-facing artifacts (prior QBRs the customer received) over internal docs. If no voice samples, the skill emits content in neutral register and flags `TONE_REVIEW_NEEDED` on the exec summary.
- **Gong coverage gaps.** If fewer than three Gong calls were logged in the quarter, the themes section is thin and over-weights whichever calls did log. Guard: the skill counts Gong calls during the parallel pull; under three, the `top_wins` slot is generated from Salesforce signal only and prefixed with `GONG_COVERAGE_LOW` so the CSM knows to add color manually.
- **Diffing to the wrong prior QBR.** If `last_qbr_path` points at a deck from a different account or quarter, the "commitments then vs reality now" framing breaks silently. Guard: the synthesis pass extracts the account name and quarter label from the prior QBR's title slide and halts if they do not match the inputs.

# QBR template slots — TEMPLATE

> Replace this template's slot list with the actual named placeholders
> in your team's QBR deck (Google Slides or PowerPoint). The qbr-prep
> skill reads this file on every run; without your real slot map, the
> skill emits content keyed to slot names that your deck-assembly script
> cannot find.

## Template identity

- `template_id`: `standard-quarterly`
- `format`: `google-slides` | `pptx`
- `template_url_or_path`: `{Drive URL or local path}`
- `last_edited`: `{YYYY-MM-DD}`

## Slot manifest

Each row is one named placeholder in the deck. The skill emits one fenced block per slot in its output Markdown; the deck-assembly script splits on the slot name and injects.

| Slot name | Slide | Data shape | Required | Notes |
|---|---|---|---|---|
| `cover_account_name` | 1 | string | yes | Pulled from Salesforce Account.Name verbatim |
| `cover_quarter` | 1 | string | yes | Format `Q{N}-{YYYY}` |
| `exec_summary` | 2 | bullet list, 5 items | yes | One fact per bullet, no adjectives |
| `usage_trend` | 3 | paragraph + chart caption | yes | Three sentences max; chart is rendered separately by the deck-assembly script from the usage CSV |
| `top_wins` | 4 | bullet list, 3 items | yes | Each bullet has outcome, metric, optional customer quote |
| `risk_summary` | 5 | table | yes | Columns: Risk, Severity, Mitigation owner, Mitigation |
| `success_plan_progress` | 6 | table | conditional | Emits `SUCCESS_PLAN_UNAVAILABLE` if no plan; deck-assembly blanks the slide |
| `expansion_paths` | 7 | numbered list, 3 items | yes | Each item names signal type and confidence |
| `next_quarter_commitments` | 8 | bullet list | yes | Editable by CSM during live call; skill seeds with carry-over from success plan |
| `appendix_call_themes` | 9 | bullet list | optional | Surfaced from Gong synthesis; only included if Gong coverage was sufficient |

## Severity vocabulary

The `risk_summary` slot uses a fixed three-value scale. Other vocabularies break the deck-assembly script's color logic.

- `red` — active blocker, escalated to AE or product
- `yellow` — emerging concern, owner assigned, no escalation yet
- `green` — resolved within the quarter, listed for visibility

## Confidence vocabulary

The `expansion_paths` slot uses a fixed three-value scale.

- `high` — usage signal AND persona signal AND budget signal present
- `medium` — two of the three signals present
- `low` — one signal, included for the live QBR conversation rather than commitment

## Usage CSV schema

The `usage_trend` slot validates against this header before generating content. Missing columns cause the slot to render blank.

| Column | Type | Description |
|---|---|---|
| `event_date` | date | One row per day |
| `metric_name` | string | Constrained to the team's metric vocabulary (DAU, WAU, key-action count) |
| `metric_value` | number | The value for that metric on that day |
| `seat_count` | integer | Active seats on that day |
| `feature_area` | string | Category for grouping in the trend narrative |

# Success-plan format — TEMPLATE

> Replace this template's contents with your team's actual success-plan
> schema. The qbr-prep skill parses the success-plan doc against this
> shape; if the parse fails, the skill halts rather than guessing.
> Adopt this same template across the CSM team so every account's plan
> reads the same way.

## Storage location

Pick one and stick to it. Mixing storage breaks the skill's `success_plan_ref` resolver.

- Notion: one page per account, parented under "Customer Success Plans"
- Salesforce: custom object `Success_Plan__c`, lookup from Account
- Gainsight: CTA of type `Success Plan`, one open at a time per account

## Required fields

The skill expects these fields, in this order. Optional fields are tolerated and ignored.

| Field | Type | Description |
|---|---|---|
| `account_id` | string | Salesforce 18-character account ID — must match the skill's input |
| `plan_owner` | string | CSM email |
| `quarter_started` | string | Quarter label, e.g. `Q4-2025` |
| `last_updated` | date | The skill flags `SUCCESS_PLAN_STALE` if older than 60 days |
| `business_outcomes` | list of objects | The customer's stated outcomes; see schema below |
| `goals` | list of objects | The measurable goals laid against each outcome; see schema below |
| `risks_known` | list of objects | Risks the CSM has already logged outside the QBR cycle |
| `next_review_date` | date | When this plan is next scheduled for refresh |

## `business_outcomes` schema

Each outcome answers "what is the customer trying to achieve in their business?"

```yaml
- outcome_id: BO-1
  statement: "Reduce time-to-onboard new sales reps from 8 weeks to 4 weeks"
  stakeholder: "VP Revenue Operations"
  priority: critical | high | medium
```

## `goals` schema

Each goal is the measurable thing the product is supposed to move. Goals are what the `success_plan_progress` slot reports against.

```yaml
- goal_id: G-1
  outcome_id: BO-1
  metric: "Average rep time-to-first-deal"
  baseline: 56  # days, recorded at plan start
  target: 28
  current: 41   # updated quarterly by the CSM
  status: on-track | at-risk | off-track | achieved | abandoned
  evidence_url: "{link to dashboard or report}"
```

## `risks_known` schema

The skill cross-references these against the synthesis pass. Risks logged here that are still active become `yellow` or `red` rows in `risk_summary`.

```yaml
- risk_id: R-1
  description: "Champion left for new role; replacement not yet identified"
  severity: red | yellow | green
  owner: csm | ae | product | customer
  logged_date: 2026-01-15
  mitigation: "AE has scheduled intro with VP RevOps for replacement champion identification"
```

## Worked example

```yaml
account_id: "0014x000ABCDEFGHIJ"
plan_owner: "alex.csm@yourco.com"
quarter_started: "Q4-2025"
last_updated: 2026-04-12
next_review_date: 2026-07-15

business_outcomes:
  - outcome_id: BO-1
    statement: "Reduce time-to-onboard new sales reps from 8 weeks to 4 weeks"
    stakeholder: "VP Revenue Operations"
    priority: critical

goals:
  - goal_id: G-1
    outcome_id: BO-1
    metric: "Average rep time-to-first-deal (days)"
    baseline: 56
    target: 28
    current: 41
    status: at-risk
    evidence_url: "https://lookerstudio.example.com/reports/onboarding-tti"

risks_known:
  - risk_id: R-1
    description: "VP RevOps champion took new role at peer company in March"
    severity: red
    owner: ae
    logged_date: 2026-03-22
    mitigation: "AE working through CFO intro for replacement champion"
```

# Sample output — fictional account

> A worked example the qbr-prep skill anchors against for tone and
> structure. The account name, metrics, and quotes here are fabricated.
> Replace this file with three to five real (anonymized) prior QBRs from
> your CSM team to give the tone-match pass real material to mimic.

# QBR draft — Northwind Logistics — Q1-2026

> Generated 2026-04-30 14:22. Status: complete.
> Missing streams: none.

## Slot: `cover_account_name`

```text
Northwind Logistics
```

## Slot: `cover_quarter`

```text
Q1-2026
```

## Slot: `exec_summary`

```text
- ARR held flat at $480k through Q1; renewal scheduled for Q3-2026.
- Active seats grew from 84 to 112 (33%); WAU grew from 61 to 89 (46%).
- Two of three success-plan goals on-track; one (rep onboarding time) at-risk.
- One open red risk: champion transition in RevOps; AE owns replacement intro.
- Proposed agenda: usage trends, success-plan review, expansion conversation around the warehouse-management module.
```

## Slot: `usage_trend`

```text
Active seats grew 33% quarter-over-quarter (84 to 112) while weekly active usage grew 46% (61 WAU to 89 WAU), indicating per-seat engagement is rising rather than diluting. The growth concentrated in the dispatch and routing feature areas, which together accounted for 71% of key-action volume in March. The reporting feature area remains under-used relative to onboarded seats — a likely topic for the live QBR.
```

## Slot: `top_wins`

```text
- Cut average dispatch latency from 9 minutes to 4 minutes after enabling automated route assignment in February ("This freed an entire shift's worth of dispatcher time" — Ops Manager, Gong call 2026-03-12).
- Closed integration backlog with the warehouse system; 12 of 12 facilities now reporting through the unified dashboard.
- Onboarded the second business unit (Eastern region) ahead of plan; 28 new seats activated in March vs Q2 target of 20.
```

## Slot: `risk_summary`

```text
| Risk | Severity | Mitigation owner | Mitigation |
|---|---|---|---|
| RevOps champion took new role; replacement not yet identified | red | ae | CFO intro scheduled for week of May 6 |
| Rep onboarding time-to-first-deal trending 41 days vs 28-day target | yellow | csm | Targeted enablement session booked for new-rep cohort May 14 |
| Reporting feature adoption flat at 22% of seats | yellow | csm | Office-hours session scheduled June; track adoption pre/post |
```

## Slot: `success_plan_progress`

```text
| Goal | Target | Actual | Status |
|---|---|---|---|
| Reduce rep time-to-first-deal | 28 days | 41 days | at-risk |
| Cut dispatch latency | 5 min | 4 min | achieved |
| Unify reporting across 12 facilities | 12/12 | 12/12 | achieved |
```

## Slot: `expansion_paths`

```text
1. **Warehouse-management module.** Signal: usage. Confidence: high. Three Gong calls in March surfaced unprompted asks for the WMS add-on; Eastern region rollout creates natural anchor. Next step: AE to scope WMS pilot with VP Operations during the live QBR.
2. **Premium support tier.** Signal: persona. Confidence: medium. Champion transition makes premium tier (named CSM, 4-hour SLA) a continuity story. Next step: surface tier comparison in the wrap-up if champion replacement question stays open.
3. **Multi-year renewal at Q3.** Signal: contract. Confidence: medium. Two-year commit unlocks 12% pricing concession; usage growth supports the math. Next step: position with CFO during champion-replacement intro, not in the QBR itself.
```

## Slot: `next_quarter_commitments`

```text
- Drive rep onboarding goal back to on-track via May 14 enablement session
- Confirm replacement RevOps champion by end of May
- Run reporting-feature office hours and track adoption delta through June
- Scope WMS pilot with VP Operations and surface a written proposal by July 1
```

## Slot: `appendix_call_themes`

```text
- "We are getting more out of dispatch than we expected" (Ops Manager, 2026-03-12)
- Three calls surfaced WMS interest unprompted (2026-02-08, 2026-03-19, 2026-03-27)
- One call mentioned competitor evaluation in passing (2026-02-22) — context was board pressure, not active eval; AE to confirm
```