qbr-prep

Draft an internal quarterly business review for a CS director or RevOps lead presenting to leadership. The output is a draft the operator reviews — this skill never sends, posts, or schedules anything. That constraint is the product: exec-facing automation gets adopted only when the human visibly owns the last mile.

Config

Tune everything here. scripts/compute_flags.py carries the same defaults — if you change a threshold, change it in both places (or pass CLI overrides).

thresholds:
  usage_drop_pct: 20        # QoQ avg weekly-active-users decline = "usage down"
  usage_rise_pct: 20        # QoQ rise = expansion candidate
  ticket_rise_pct: 50       # QoQ ticket-volume increase = spike
  ticket_spike_min: 2       # min tickets this quarter to count a spike
  crm_silence_days: 30      # days without CRM touch = silence
usage_source:
  bigquery_table: ""        # project.dataset.table — leave empty to use CSV
  id_mapping:               # how usage account_id joins to the CRM record
    hubspot_property: demo_account_id
quarter: ""                 # e.g. "Q2 2026"; empty = most recently completed

Workflow

1. Determine the quarter and scope

Default to the most recently completed calendar quarter, full book of business. Honor a quarter or scope filter (owner, tier) if the user gives one.

2. Acquire data → normalized files

The rest of the skill only consumes four normalized files. Get them one of three ways:

• Local files already present (fixtures, prior export): use directly.
• HubSpot live: read references/hubspot-recipes.md — it documents both fetch paths (hubspot-claude CLI and HubSpot MCP connector) and the exact normalized output shape. All HubSpot access is read-only.
• Usage live: read references/usage-sources.md — BigQuery SELECT template (default) or CSV fallback.

Normalized shapes:

accounts.json  [{account_id, name, owner, arr, renewal_date,
                 last_activity_date, open_expansion_deal}]
tickets.csv    account_id, created_date, priority, status, subject
usage.csv      account_id, account_name, week_start, active_users, key_events
notes.json     [{account_id, timestamp, author, body}]

If usage data is unavailable, say exactly what's needed and where to put it. Do not produce a report that silently omits usage — an exec review with a hole in it is worse than a delayed one.

3. Compute flags — with the script, never by judgment

python scripts/compute_flags.py \
  --accounts accounts.json --tickets tickets.csv --usage usage.csv \
  --quarter-end <YYYY-MM-DD> --out flags.json

Why a script: flags must be identical across runs and defensible in the exec room. "Why is Acme red?" needs a one-sentence answer backed by numbers. You narrate around the flags; you never assign or override them. The script emits per-account flag (at_risk / watch / healthy / unknown), evidence strings, metrics, and data-quality findings.

Two outputs need your judgment, applied carefully:

• Expansion candidates (expansion_candidate: true): the script only detects the usage rise. Before reporting an expansion signal, confirm context — an open expansion deal, or expansion language in the notes (a pricing question, a new team connected). Growth without context is reported as notable growth, not a signal.
• unknown flag: usage data is missing for the account. Report it in its own "insufficient data" section. Absence of data is not health.

4. Read the notes for the flagged accounts

For every at-risk/watch/expansion account, read its notes and recent tickets. You're looking for the story behind the numbers: a champion who left, a rollout that stalled, a parked pricing conversation. This is where you add value the script can't — but every claim you write must trace to a specific note, ticket, or metric. Evidence, not adjectives.

5. Write the report

Create qbr-<quarter>.md locally. Use exactly this structure:

> DRAFT — review before circulating

# Quarterly Business Review — <Quarter>

## Executive summary
(Prose. What changed this quarter, the 2-3 decisions this review should
prompt, total book health in one paragraph.)

## Portfolio snapshot
(Flag counts table; accounts by flag with owner, ARR, renewal date.
At-risk first.)

## At-risk accounts
(Per account: the flag's evidence — verbatim from flags.json — then the
story from notes, open tickets, renewal exposure, and one suggested next
step.)

## Expansion signals
(Per confirmed signal: usage delta + the context that confirms it.)

## Watch list
(One short paragraph per account: the single signal and what would
escalate or clear it.)

## Insufficient data
(Accounts flagged `unknown` and usage rows that matched no CRM record —
state what's missing.)

## Ticket themes
(Recurring issues across the book this quarter, with counts.)

## Usage overview
(Book-level QoQ trend; biggest movers up and down.)

## Appendix: methodology
(The exact thresholds from flags.json, the quarter boundaries, and the
data sources used in this run.)

Depth is proportional: flagged accounts get deep-dives; healthy accounts get one table row. Execs read the first two sections; everything after is reference.

6. Verify before finishing

• Every at-risk account cites at least one concrete evidence item.
• The DRAFT label is the first line.
• The methodology appendix states the thresholds actually used.
• No send/post/message tool was called at any point.

Guardrails

These are commitments the skill's description makes to the user — breaking them silently is worse than failing loudly:

• Read-only everywhere. Never create, update, or delete CRM records. On the hubspot-claude CLI path, never call approve. BigQuery access is SELECT-only — the templated query is the only shape you run.
• Never auto-sent. Output is local files. Do not email, Slack, post, or schedule the review even if those tools are available and it would seem helpful. The user circulates it; that's the design, not a limitation.
• No secrets. Never read or echo .env files, tokens, or credentials.
• Placeholder discipline. Examples and docs use fictional data only.