{
  "name": "data-analytics-team-pack",
  "version": "0.1.0",
  "description": "ContextCake Pack for data and analytics teams.",
  "author": {
    "name": "ContextCake"
  },
  "license": "UNLICENSED",
  "keywords": ["contextcake", "analytics", "data-team", "okf"]
}

---
type: example
updated: 2026-07-06
---

# Bad Request, Good Clarification {#bad-request-good-clarification}

A side-by-side of what happens when a vague stakeholder request goes straight to a
build versus when it goes through `workflows/request-clarification.md` first.
Fictional company, fictional numbers — Northwind.

## The request {#the-request}

Slack message from a Northwind customer success manager:

> "Can I get the churn numbers?"

Five words. No definition, no window, no source, no audience. This is a
`glossary/stakeholder-request.md` in its rawest form — and it's an easy one to get
wrong, because "churn" sounds precise even though it isn't defined.

## The bad path {#the-bad-path}

An analyst under deadline pressure skips clarification and builds immediately, making
silent assumptions to keep moving:

- **Assumes** "churn" means logo churn (accounts lost), when the CS manager was actually
  asking about revenue churn for a renewal-risk conversation.
- **Assumes** a trailing-3-month window because that's what the last churn request used,
  with no basis for this one.
- **Pulls from the CRM** because it's the fastest system to query, not the billing
  system — see `policies-and-rules/source-of-truth-precedence.md` on why that's the
  wrong default for anything revenue-shaped.
- **Skips validation** — no reconciliation to a control number, no record-count check,
  ships straight from query to Slack reply.

The number gets sent back as a single figure with no method, no confidence, and no
caveats. Two days later the CS manager forwards it to their VP, who asks "is this logo
churn or revenue churn?" — and the analyst can't say for certain which one they
computed, because the assumption was never written down. The number gets pulled back and
redone, costing more time than clarifying up front would have.

## The good path {#the-good-path}

Same request, run through `workflows/request-clarification.md` using the prompts in
`prompt-guides/clarifying-a-stakeholder-request.md`. The analyst asks three questions
before touching a query:

1. "When you say churn, do you mean accounts lost (logo churn) or revenue lost (revenue
   churn)?"
2. "What's this for — a specific conversation or a standing report?"
3. "What time window matters — this month, this quarter, trailing 12 months?"

The CS manager clarifies: revenue churn, for a renewal-risk conversation with a specific
at-risk account's account executive, trailing 3 months, ahead of Thursday's account
review.

That turns into a clarified spec using `templates/clarified-spec-template.md`:

**Request (verbatim):** "Can I get the churn numbers?"
**Decision it informs:** Renewal-risk conversation with an account executive ahead of
Thursday's account review.
**Question (restated):** How much recognized MRR was lost to contraction and churn over
the trailing 3 months?
**Metric definition(s):** Revenue churn (contraction + full churn), not logo churn. See
`glossary/metric-definitions.md`.
**Source of truth:** The billing system, not the CRM — per
`policies-and-rules/source-of-truth-precedence.md`.
**Grain:** Monthly.
**Filters / segments:** Contraction and churn only; excludes new and expansion.
**Time window:** Trailing 3 months.
**Acceptance criteria:** Monthly totals reconcile to the billing system's finance-blessed
churn figure within tolerance.
**Deadline:** Wednesday end of day, ahead of Thursday's account review.
**Owner:** CS manager (requester).
**Open questions:** None — definition and window confirmed directly.

Built and validated against the billing system per `workflows/build-and-validate.md` and
`templates/validation-checklist-template.md`, then delivered as an insight summary with
a headline answer, confidence level, and named caveats — not a bare number in a Slack
reply.

## The difference {#the-difference}

The bad path was faster by about ten minutes and slower by two days once the rework is
counted. The good path spent those ten minutes turning an ambiguous word — "churn" —
into a named metric definition and a named source of truth, both written down where the
next person to touch this request can see them. That's the entire value of
`workflows/request-clarification.md`: it's cheap insurance against building the right
answer to the wrong question.

---
type: example
updated: 2026-07-06
---

# Worked Example: MRR Request {#worked-example-mrr-request}

A full pass through the hero workflow (`workflows/stakeholder-request-to-insight.md`),
start to finish, on the request every analytics team gets sooner or later: "how's MRR
doing?" Fictional company, fictional numbers — Northwind, a B2B SaaS.

## The request {#the-request}

Slack message from Northwind's VP of Sales, Thursday afternoon:

> "Hey — can someone pull our MRR trend for the board deck? Need it by Monday."

Six words of metric, zero words of definition. This is the default shape of a
stakeholder request — see `glossary/stakeholder-request.md`. Don't build yet.

## Phase 1: Clarify {#phase-1-clarify}

The analyst runs the request through `workflows/request-clarification.md` and comes
back with a clarified spec, using `templates/clarified-spec-template.md` and the
prompts in `prompt-guides/clarifying-a-stakeholder-request.md`:

**Request (verbatim):** "Can someone pull our MRR trend for the board deck? Need it by
Monday."
**Decision it informs:** Quarterly board deck — investor-facing narrative on revenue
momentum.
**Question (restated):** How has recognized monthly recurring revenue trended over the
trailing 12 months, broken out by new, expansion, contraction, and churn?
**Metric definition(s):** Recognized MRR (billing-system definition), not committed or
booked MRR. See `glossary/metric-definitions.md` for why this distinction matters.
**Source of truth:** The billing system (Northwind's subscription ledger), not the CRM.
The CRM tracks pipeline and bookings, not recognized revenue — see
`policies-and-rules/source-of-truth-precedence.md`.
**Grain:** Monthly.
**Filters / segments:** New, expansion, contraction, churn. Excludes one-time services
revenue.
**Time window:** Trailing 12 months, ending last closed month.
**Acceptance criteria:** Monthly totals reconcile to the billing system's finance-blessed
MRR number within rounding; segment breakout sums to the total.
**Deadline:** Monday, 9am, ahead of Tuesday's board prep review.
**Owner:** VP of Sales (requester); Finance is a stakeholder on the number.
**Open questions:** None outstanding — confirmed recognized (not committed) MRR with the
VP of Sales directly.

## Phase 2: Build {#phase-2-build}

The analyst builds against the billing system's subscription ledger per
`workflows/build-and-validate.md`: one query per month in the window, summing active
subscription value at month-end, split into the four segments by comparing each
account's current-month value to its prior-month value (new = no prior value,
expansion/contraction = value changed, churn = value dropped to zero). Query and output
saved to the team's shared notebook location so the result is reproducible.

## Phase 3: Validate {#phase-3-validate}

Run through `templates/validation-checklist-template.md`:

- Source of truth identified — billing system ledger, confirmed with Finance.
- Metric definition matches the agreed definition — recognized MRR, confirmed.
- Grain correct — monthly, confirmed.
- Filters/segments applied correctly — spot-checked five accounts against each segment
  bucket by hand.
- Record counts reconcile — subscription row count matches billing system's active count
  for the current month.
- Totals reconcile to a source-of-truth control number — Finance's month-end MRR figure
  for the most recent closed month is a **synthetic control value of $1,842,000**. The
  query's independently computed total for that month is $1,839,500, a $2,500 (0.14%)
  gap — inside the team's agreed 0.5% reconciliation tolerance.
- Sample rows spot-checked — five accounts traced end to end from ledger row to segment
  bucket.
- Nulls & duplicates checked — no null subscription values in the window; no duplicate
  account-month rows.
- Date boundaries / time zone correct — month-end cutoff aligned to billing system's
  close calendar (UTC), not calendar month-end.
- Result is reproducible — query saved to the shared notebook location referenced above.
- Peer reviewed — a second analyst re-ran the query and confirmed the same total.

Validation passes (`glossary/validation-pass.md`) at a $2,500 gap on a $1.84M total —
well inside tolerance and explained by two subscriptions that renewed mid-day on the
boundary date.

## Phase 4: Deliver {#phase-4-deliver}

Insight summary, per `workflows/insight-delivery.md` and
`templates/insight-summary-template.md`:

**Headline answer:** Recognized MRR grew 18% over the trailing 12 months, driven mainly
by expansion revenue from existing accounts.
**Confidence:** High — reconciled to the billing system's finance-blessed control number
within 0.14%, well inside tolerance.
**Key numbers:** Trailing-12-month MRR grew from $1.56M to $1.84M. Expansion contributed
$210K of the $280K net gain; new business contributed $140K; contraction and churn
offset $70K.
**What it means for the decision:** The board narrative can lean on expansion as the
primary growth engine, not new-logo acquisition — worth flagging if the deck currently
implies otherwise.
**Caveats & assumptions:** Recognized MRR, not committed/booked. Segment classification
uses month-over-month account value comparison, not a stamped event log — mid-month
plan changes are attributed to the month they took effect in the ledger.
**Method:** Source — billing system ledger. Definition — recognized MRR. Window —
trailing 12 months, monthly grain.
**Next action:** Hand off to VP of Sales for board deck integration; Finance cc'd for
awareness given the number appears in investor materials.
**Links / appendix:** Saved query location noted in the team's shared notebook; this
worked example for future MRR requests.

---
type: example
updated: 2026-07-06
---

# Worked Example: Recurring Report Break {#worked-example-recurring-report}

A second worked case: not a new request, but a standing report that quietly went wrong.
This is the failure mode `workflows/recurring-report-refresh.md` and
`policies-and-rules/metric-change-control.md` exist to catch. Fictional company,
fictional numbers — Northwind.

## The setup {#the-setup}

Northwind's weekly executive dashboard includes "active accounts" — a headline tile the
CEO reads every Monday. The metric has been stable for a year: a straightforward count
of accounts with `status = active` in the product database.

## What broke {#what-broke}

Monday's refresh shows active accounts up ~20% week over week. No unusual sales
activity, no bulk import, nothing in the changelog. The number is implausible on its
face, but it's not obviously wrong either — it just jumped.

This is a recurring-report refresh, not a new stakeholder request, so it runs through
`workflows/recurring-report-refresh.md` rather than a fresh clarify phase — but the same
validation discipline applies.

## Phase 3: Validate catches it {#phase-3-validate-catches-it}

Before the dashboard ships, the analyst runs `templates/validation-checklist-template.md`
as required by the refresh workflow:

- Source of truth identified — product database `accounts` table, unchanged.
- Metric definition matches the agreed definition — **fails here.** The agreed
  definition of "active" (per `glossary/metric-definitions.md`) is a paying,
  non-trial account in good standing. Spot-checking new "active" accounts turns up
  several accounts still in their 14-day trial period.
- Totals reconcile to a source-of-truth control number — the CRM's paid-account count
  (a synthetic control value of **1,240**) does not match the dashboard's new "active"
  count of **1,488** — a 20% gap, well outside tolerance.
- Sample rows spot-checked — confirms trial accounts are present in the new count and
  were absent last week.

The checklist stops the refresh from shipping. Digging into the product database's
schema history: an upstream engineering change three days earlier redefined the
`active` flag to include trial accounts, for an unrelated onboarding-funnel feature. No
one told the analytics team.

## The root cause {#the-root-cause}

This is exactly the scenario `policies-and-rules/metric-change-control.md` exists for:
an upstream system changed a field's meaning without notifying downstream consumers of
that field. The metric name (`active`) stayed the same; the definition underneath it
did not. Nothing in the pipeline itself broke — no errors, no failed job — which is why
it's dangerous. A silent definition change reads as legitimate growth unless someone
reconciles to a control number.

## Fix {#fix}

- Report the discrepancy to the engineering owner of the `active` flag and confirm the
  new field semantics.
- Update the dashboard query to filter explicitly on paying, non-trial status —
  `status = active AND trial_ends_at IS NULL` — restoring the original metric
  definition rather than inheriting whatever the upstream flag happens to mean.
- Log the change per `policies-and-rules/metric-change-control.md` so future
  upstream changes to fields this report depends on get flagged before they ship, not
  after.
- Add a note to the report's saved query documenting the incident and the explicit
  filter, so the next analyst who touches this report understands why the filter is
  more verbose than the flag alone.

## Corrected insight summary {#corrected-insight-summary}

**Headline answer:** Active accounts (paying, non-trial) held flat at 1,240 week over
week — the earlier 1,488 figure was inflated by a silent upstream definition change that
added trial accounts.
**Confidence:** High — reconciled to the CRM's paid-account control number after
correcting the filter.
**Key numbers:** 1,240 active accounts this week vs. 1,235 last week (+0.4%), consistent
with recent trend. The uncorrected figure (1,488) is not usable.
**What it means for the decision:** No change to the growth narrative. Do not circulate
the 1,488 figure that already went out in the earlier draft — send a correction.
**Caveats & assumptions:** Depends on the `active`/`trial_ends_at` fields in the product
database keeping their current meaning; flagged as change-controlled per
`policies-and-rules/metric-change-control.md`.
**Method:** Source — product database `accounts` table, CRM paid-account count as
control. Definition — paying, non-trial account. Window — current week vs. prior week.
**Next action:** Send correction to dashboard recipients; confirm with engineering that
no other downstream reports read the `active` flag without the trial filter.
**Links / appendix:** `workflows/recurring-report-refresh.md`,
`policies-and-rules/metric-change-control.md`, incident note in the report's saved
query documentation.

---
type: glossary
updated: 2026-07-06
---

# Clarified Spec {#clarified-spec}

## Definition {#definition}

A clarified spec is the written, scoped version of a stakeholder request: the raw
question plus everything an analyst needs to build and validate an answer without
guessing. It is the output of the Clarify phase and the input to the Build phase.

## Why it matters {#why-it-matters}

The clarified spec is what turns "how is MRR trending?" into something you can actually
query. Skipping it doesn't save time — it just moves the scoping conversation from before
the build (cheap) to after delivery, when the stakeholder challenges the number (expensive,
and now it looks like an error rather than a scoping step). A written spec also gives you
something concrete to send back to the stakeholder for a fast confirm before you spend
build time on the wrong definition.

## Canonical fields {#canonical-fields}

Every clarified spec uses the same field names, in this order: Request (verbatim) ·
Decision it informs · Question (restated) · Metric definition(s) · Source of truth · Grain
· Filters / segments · Time window · Acceptance criteria · Deadline · Owner · Open
questions. Use `templates/clarified-spec-template.md` to fill these in — don't
reinvent the field set per request, the consistency is what makes specs easy to review and
compare later.

Two fields are worth calling out because they're the ones people skip: **Decision it
informs** forces you to ask why the number matters before you build it, which shapes
everything downstream (a board-deck number needs tighter validation than a quick
directional check). **Open questions** is where you park anything you couldn't resolve
before the deadline — better an explicit gap than a silent assumption.

## Northwind example {#northwind-example}

For the VP of Sales's MRR question, the clarified spec records: Decision — the quarterly
board deck; Question — is MRR trending up or down, and why; Metric definition — committed
MRR (not recognized revenue); Source of truth — the billing system; Grain — monthly;
Filters/segments — new, expansion, contraction, churn; Time window — trailing 12 months;
Acceptance criteria — reconciles to the billing system's finance-blessed total within
rounding. The VP confirms this in two Slack messages before any query is written.

## See also {#see-also}

- `templates/clarified-spec-template.md`
- `glossary/stakeholder-request.md`
- `workflows/request-clarification.md`

---
type: glossary
updated: 2026-07-06
---

# Insight Summary {#insight-summary}

## Definition {#definition}

An insight summary is the delivered output of a request: a short, structured writeup
that leads with the answer and carries its own confidence level, caveats, and next action.
It is the output of the Deliver phase — what the stakeholder actually reads, as opposed to
the query or notebook behind it.

## Why it matters {#why-it-matters}

A validated number delivered as a raw table or a chart with no context forces the
stakeholder to infer the confidence, caveats, and implications themselves — and they will
usually infer the most convenient version, not the most accurate one. An insight summary
does that interpretation work once, explicitly, so the stakeholder can't accidentally
overstate what the data shows. It also makes the analyst's judgment visible and
reviewable: a stated "Medium confidence, because segment attribution changed mid-quarter"
is something a peer or the stakeholder can push back on; a bare number is not.

## Canonical fields {#canonical-fields}

Every insight summary uses the same field names: Headline answer · Confidence (High /
Medium / Low, plus one reason) · Key numbers · What it means for the decision · Caveats &
assumptions · Method (source, definition, window) · Next action · Links / appendix. Use
`templates/insight-summary-template.md` to fill these in. The **Confidence** and **Caveats**
fields are not optional padding — they're what separates an insight summary from a
dashboard screenshot, and they're what protects the stakeholder from over-reading a number
you know has soft spots.

## Northwind example {#northwind-example}

The MRR insight summary for the VP of Sales leads with: "MRR grew 4% over the trailing 12
months, driven by expansion revenue outpacing churn in the last two quarters." Confidence:
High, reconciled to billing system finance close. Caveats: one enterprise contract
renewal was delayed into next month and is not yet reflected. Next action: flag the
delayed renewal to the CFO before the board deck locks. The VP gets a decision-ready
answer, not a chart to interpret alone.

## See also {#see-also}

- `templates/insight-summary-template.md`
- `workflows/insight-delivery.md`
- `glossary/validation-pass.md`

---
type: glossary
updated: 2026-07-06
---

# Metric Definitions {#metric-definitions}

## Definition {#definition}

A metric definition is the precise, written rule for how a named metric is calculated:
what counts, what doesn't, and what edge cases resolve which way. "MRR" is not a metric
definition. "Committed MRR: the sum of active subscription contract values as of month-end,
excluding trials, in the billing system's base currency" is.

## Why it matters {#why-it-matters}

Most metric names are ambiguous even inside a single company. "Active accounts,"
"revenue," "churn" — each of these has multiple defensible definitions, and different
systems often compute them differently by default. A metric definition removes the
ambiguity once, in writing, so the analyst building a report and the stakeholder reading
it are talking about the same number. Definitions also drift: someone changes what
`active` means in a source table, and every downstream report silently starts answering a
different question. That's why definitions need a change-control process, not just an
initial write-up — see `policies-and-rules/metric-change-control.md`.

## Using metric definitions {#using-metric-definitions}

Record the specific definition in play as part of every clarified spec (the "Metric
definition(s)" field — see `glossary/clarified-spec.md`), even for metrics your team
considers standard. During validation, confirm the build actually implements the stated
definition, not just a plausible one (see `glossary/validation-pass.md`). If a stakeholder's
implicit definition differs from your team's standard one, that's a clarification
conversation, not a silent judgment call.

## Northwind example {#northwind-example}

Northwind's dashboard has tracked "active accounts" for two years using the definition
"accounts with a paid subscription in the billing system." An engineer updates the
`active` flag in the product database to also include accounts in an active trial, to
support a different feature. The dashboard, which reads that flag directly instead of the
billing system, jumps 20% overnight with no change in actual paying customers. The jump
gets caught during the weekly validation pass because the dashboard total no longer
reconciles to the billing system's account count — the metric definition changed
underneath the report without going through change control.

## See also {#see-also}

- `policies-and-rules/metric-change-control.md`
- `glossary/clarified-spec.md`
- `glossary/source-of-truth.md`

---
type: glossary
updated: 2026-07-06
---

# Source of Truth {#source-of-truth}

## Definition {#definition}

The source of truth for a metric is the single system whose numbers are authoritative
for that metric — the one you reconcile to when two systems disagree. It is a choice your
team makes and documents, not a property a system has on its own.

## Why it matters {#why-it-matters}

Most contested numbers aren't math errors — they're two people trusting two different
systems that both look reasonable. A CRM's opportunity amounts and a billing system's
invoiced amounts can both be "correct" and still disagree, because they measure different
things (a sale versus a payment). Without a named source of truth, every disagreement
becomes a fresh argument. With one, it becomes a lookup: check the designated system,
done.

## How to choose one {#how-to-choose-one}

Pick the system closest to the actual event, not the system that's easiest to query.
For revenue metrics that's usually the billing or finance system, not the CRM. For product
usage it's usually the event pipeline, not a dashboard that samples it. When a metric
doesn't have an obvious owner, escalate the choice to whoever is accountable for the
decision the metric informs, and record the decision in
`policies-and-rules/source-of-truth-precedence.md` so it doesn't get re-litigated per
request.

## Source of truth vs. system of record {#source-of-truth-vs-system-of-record}

The two terms get used interchangeably, but they answer different questions. A **system
of record** is where data is created and lives operationally — the CRM is the system of
record for opportunity stage, the billing platform is the system of record for invoices.
A **source of truth** is which system you trust for a specific metric's value when systems
disagree. Usually the system of record for the underlying event *is* the source of truth
for metrics derived from it, but not always: a data warehouse that cleans and reconciles
multiple systems can be the source of truth for a metric even though it isn't the system
of record for any of the raw inputs.

## Northwind example {#northwind-example}

Northwind's CRM shows a customer's subscription value the moment a deal closes. Northwind's
billing system shows the value only once the subscription is provisioned and the first
invoice is generated, a few days later. For "current MRR," Northwind's analytics team
designates the billing system as the source of truth — it reflects what's actually being
charged, not what sales expects to charge. The CRM number is still useful for sales
forecasting, but it is not the number that goes in the board deck.

## See also {#see-also}

- `policies-and-rules/source-of-truth-precedence.md`
- `glossary/validation-pass.md`
- `glossary/metric-definitions.md`

---
type: glossary
updated: 2026-07-06
---

# Stakeholder Request {#stakeholder-request}

## Definition {#definition}

A stakeholder request is the raw, as-received ask from someone outside the analytics
team — a question, a Slack message, a meeting action item — before it has been scoped
into a clarified spec. It is the input to the Clarify phase, not the thing you build
against.

## Why it matters {#why-it-matters}

Stakeholder requests are almost always underspecified on purpose: the person asking
isn't thinking about metric definitions, source systems, or grain, they're thinking about
a decision they need to make. Treating the raw request as if it were already a build spec
is the single most common source of rework — you build the wrong thing correctly, ship
it, and get sent back to start over once the stakeholder sees a number that doesn't match
what they meant. Capturing the request verbatim, before you interpret it, also gives you
something to check your clarified spec against later if the stakeholder disputes the
framing.

## Handling a request {#handling-a-request}

Record the request verbatim as the first field of the clarified spec (see
`glossary/clarified-spec.md`) before you start interpreting it. Resist the urge to
silently "fix" the question while writing it down — if it's ambiguous, that ambiguity is
exactly what clarification is for. The full intake process lives in
`workflows/request-clarification.md`.

## Northwind example {#northwind-example}

Northwind's VP of Sales messages the analytics team: *"How is MRR trending?"* That's the
stakeholder request — five words, no definition of MRR, no time window, no stated
decision. It is recorded exactly as sent. The analyst does not guess at "trailing 12
months, committed MRR" and start building; that interpretation happens explicitly in the
next step, and gets written down as its own field so the VP can confirm or correct it.

## See also {#see-also}

- `glossary/clarified-spec.md`
- `workflows/request-clarification.md`
- `examples/worked-example-mrr-request.md`

---
type: glossary
updated: 2026-07-06
---

# Validation Pass {#validation-pass}

## Definition {#definition}

A validation pass is the checked, repeatable set of steps you run on a build to confirm
it matches the clarified spec and reconciles to the source of truth before it ships. It
is the output of the Validate phase — the gate between "the query ran" and "the number is
trustworthy."

## Why it matters {#why-it-matters}

A query that runs without error is not the same as a query that answers the right
question correctly. Wrong joins, double-counted rows, an off-by-one date boundary, or a
timezone mismatch all produce a number that looks plausible and is wrong. A validation
pass catches these before a stakeholder does — finding a discrepancy in review is a
non-event; finding it after the number is in a board deck is a credibility problem. It
also gives you a paper trail: when a number is challenged later, you can point to what was
checked rather than re-deriving trust from scratch.

## Running a validation pass {#running-a-validation-pass}

Work through `templates/validation-checklist-template.md` item by item — source of truth
identified, metric definition matches the agreed definition, grain correct, filters and
segments applied correctly, record counts reconcile, totals reconcile to a source-of-truth
control number, sample rows spot-checked, nulls and duplicates checked, date boundaries
and time zone correct, result is reproducible, peer reviewed. Don't skip items because the
build "looks right" — the checklist exists specifically to catch the errors that look
right. The full procedure, including what to do when reconciliation fails, is in
`workflows/build-and-validate.md`.

## Northwind example {#northwind-example}

For the VP of Sales's MRR build, the analyst runs the validation pass before sending
anything: confirms the query uses committed MRR (not recognized revenue), confirms the
billing system is the source queried, reconciles the trailing-twelve-month total to
finance's monthly-close number within rounding, spot-checks five accounts against the
billing UI directly, and confirms no duplicate subscription rows from a known join issue
with add-ons. Only after all items pass does the build move to the Deliver phase.

## See also {#see-also}

- `templates/validation-checklist-template.md`
- `workflows/build-and-validate.md`
- `glossary/source-of-truth.md`

# Local Overlay

This directory documents the overlay pattern. It is not a customer's real overlay.

Keep installed pack files clean. Put team-specific policies, source-of-truth exceptions, examples,
and style rules in your own project or team context so pack updates can be compared and merged
without overwriting local edits.

---
type: overview
updated: 2026-07-06
---

# Pack Purpose {#pack-purpose}

## What this pack is {#what-this-pack-is}

This pack is operating knowledge for small data and analytics teams: a shared way to
take a stakeholder request from a vague Slack message to a validated, delivered answer.
It is not a course and not a style guide. It is the checklist, vocabulary, and templates
your team actually uses on every request, written down once so you stop reinventing them.

## Who it's for {#who-its-for}

Small in-house data and analytics teams, roughly 2-8 people: report builders, SQL
analysts, analytics engineers, PM-adjacent analysts, CS-ops partners, and the technical
manager who owns the queue. If your team fields recurring "can you pull..." and "why did
this number move..." requests from stakeholders who are not themselves analysts, this
pack is for you.

## The one problem it solves {#the-one-problem-it-solves}

Small analytics teams answer the same shape of request over and over: a stakeholder
asks an ambiguous question, someone builds something fast, the number gets challenged in
a meeting, and nobody can reconstruct why it doesn't match what finance or the CRM shows.
The team loses trust one contested number at a time.

This pack fixes the recurring failure points with a repeatable path: scope the request
before building (`workflows/request-clarification.md`), validate every build against a
named source of truth before it ships (`workflows/build-and-validate.md`), and deliver
answers in a format that carries its own confidence and caveats
(`workflows/insight-delivery.md`). The full path is documented end to end in
`workflows/stakeholder-request-to-insight.md`.

## A short tour {#a-short-tour}

- `overview/` — this file and `overview/team-shapes.md`, on where this pack fits your team's shape.
- `glossary/` — shared vocabulary: source of truth, stakeholder request, clarified spec,
  metric definitions, validation pass, insight summary. Read these once so the rest of
  the pack reads as plain English.
- `workflows/` — the four-phase hero workflow: clarify, build, validate, deliver.
- `templates/` — the clarified-spec, validation-checklist, and insight-summary templates
  you fill in on every request.
- `policies-and-rules/` — precedence rules for source of truth and metric change control,
  for when two systems disagree or a definition changes underneath you.
- `prompt-guides/` — prompts for using this pack with an AI assistant during clarification.
- `examples/` — a worked example (an MRR trend request) that ties the whole pack together.
- `tool-guides/` — how to use this pack with Claude Code specifically.

## How to use it {#how-to-use-it}

Three equivalent ways to consume this pack, pick whichever fits your setup:

- **Plain files.** Read the markdown directly, top to bottom, starting with
  `START-HERE.md`. No tooling required.
- **Claude Code plugin.** Install the pack so `SKILL.md` and its linked files are
  available to Claude Code as project context. See `tool-guides/using-with-claude-code.md`.
- **OKF-compatible bundle.** Every content file carries OKF frontmatter (`type`,
  `updated`) and anchored headings, so the pack can be read as a layer by ContextCake's
  resolver alongside your team's own context layers.

## What this is not {#what-this-is-not}

- **Not a BI tool.** It doesn't build dashboards or run queries. It's the process and
  vocabulary around the query.
- **Not a warehouse connector.** There's no integration with your database, dbt project,
  or notebook environment. You bring your own stack.
- **Not a live-metrics service.** Nothing here refreshes automatically or holds current
  numbers. Every example is illustrative and static; the pack teaches the method, not the
  metric values.

## See also {#see-also}

- `overview/team-shapes.md`
- `workflows/stakeholder-request-to-insight.md`
- `glossary/source-of-truth.md`

---
type: overview
updated: 2026-07-06
---

# Team Shapes {#team-shapes}

Small data and analytics teams tend to fall into a handful of recognizable shapes. This
pack works for all of them, but the friction it removes shows up differently in each one.
Use this to see where your team sits and which parts of the pack to lean on first.

## The solo analyst {#the-solo-analyst}

One person, every request. No peer to sanity-check a query before it goes out, and no
shared memory beyond whatever is in that person's head or old Slack threads. The biggest
risk is silent scope drift: the stakeholder's question quietly changes between the ask
and the delivery, and there's no one else to catch it.

This pack helps most here as an external memory: the clarified-spec template
(`templates/clarified-spec-template.md`) replaces the analyst's head as the record of
what was actually asked, and the validation checklist
(`templates/validation-checklist-template.md`) stands in for a peer reviewer when there
isn't one.

## The 2-3 person report team {#the-2-3-person-report-team}

A small team splitting recurring report and ad hoc request work. The main failure mode is
inconsistency: two analysts answer similar questions with different metric definitions or
different validation rigor, and stakeholders notice the numbers don't line up.

This pack helps by making the definitions shared rather than personal —
`glossary/metric-definitions.md` and `policies-and-rules/source-of-truth-precedence.md`
apply the same way regardless of who picks up the request. Use
`workflows/build-and-validate.md` as the common bar every teammate's build clears before
delivery.

## The analytics-engineering pod {#the-analytics-engineering-pod}

A team that owns models and pipelines as well as ad hoc requests, usually with a dbt-style
project and a stronger notion of "the warehouse is the source of truth." The risk here is
inward focus: the team optimizes the model layer but under-invests in how a request enters
the queue and how an answer leaves it, so stakeholders still get inconsistent framing even
when the underlying numbers are solid.

This pack helps by bracketing the engineering work with the same clarify-and-deliver
discipline: `workflows/request-clarification.md` scopes what a model change is actually
for, and `workflows/insight-delivery.md` makes sure a technically correct number still
lands as a usable answer.

## The PM-embedded analyst {#the-pm-embedded-analyst}

An analyst embedded in a product or growth team, reporting into a PM rather than a central
data org. Requests arrive fast and informally, often mid-meeting, and there is pressure to
answer immediately rather than scope first. The risk is that "fast" quietly becomes
"unvalidated," and a number said out loud in a meeting becomes the de facto truth before
anyone reconciles it.

This pack helps by making clarification cheap enough to do even under time pressure — the
clarified-spec fields in `templates/clarified-spec-template.md` fit in a few lines — and
by giving the analyst a fast validation pass
(`glossary/validation-pass.md`) to run before a number leaves the room.

## See also {#see-also}

- `overview/pack-purpose.md`
- `workflows/stakeholder-request-to-insight.md`
- `glossary/validation-pass.md`

---
type: policy
updated: 2026-07-06
---

# Metric Change Control {#metric-change-control}

A metric definition is a contract: everyone downstream assumes it means what it meant
last week. This policy governs how a definition is proposed, reviewed, versioned, dated,
and communicated when it needs to change — so a redefinition never reaches a stakeholder
as a silent, unexplained jump in a familiar number. See
`glossary/metric-definitions.md` for how definitions are documented day to day.

## Why silent redefinitions are dangerous {#why-silent-redefinitions-are-dangerous}

At Northwind, a weekly executive dashboard's "active accounts" figure jumped roughly 20%
week over week. Nothing about actual usage had changed — an engineer had widened the
upstream `active` flag to include trial accounts, to fix an unrelated reporting gap. The
dashboard kept running without error and produced a plausible-looking number, which is
what made it dangerous: nobody was prompted to question it until a stakeholder asked why
active accounts suddenly beat forecast. The fix wasn't technical — the flag change was
reasonable in isolation — it was that nobody proposed, reviewed, or announced it as a
metric definition change.

Every silent redefinition costs trust even after it's explained, because it retroactively
puts every past report in doubt: if this number moved without anyone knowing, which
others already have?

## How a change is proposed {#how-a-change-is-proposed}

1. Anyone who wants to change a metric definition — including an engineer changing an
   upstream field a metric depends on — writes a short proposal: current definition, new
   definition, reason for the change, and which dashboards/reports/models depend on it.
2. Search for the metric's existing entry in `glossary/metric-definitions.md` and any
   report that references it before proposing — you need the full blast radius, not just
   the report you're currently working on.

## How a change is reviewed {#how-a-change-is-reviewed}

1. At least one other analyst or the team's technical manager reviews the proposal
   against every known consumer of the metric.
2. Reviewers check whether the change should be a new metric (e.g. `active_accounts_v2`)
   instead of a redefinition in place — this is usually the safer choice when historical
   comparability matters, such as board-level trend metrics.
3. If the metric feeds an insight summary that's already been delivered, flag whether
   past deliverables need a retroactive caveat.

## How a change is versioned and dated {#how-a-change-is-versioned-and-dated}

- Update `glossary/metric-definitions.md` with the new definition, the effective date,
  and a note of what the prior definition was — do not overwrite history, append to it.
- If the change breaks comparability with prior periods, say so explicitly next to the
  definition (e.g. "not comparable to weeks before 2026-06-30").
- Prefer a new metric name over a silent redefinition whenever a trend line or
  board-level number depends on the old definition holding steady.

## How a change is communicated {#how-a-change-is-communicated}

- Announce the change to the team and to any stakeholder who regularly consumes the
  metric, before it goes live wherever possible — not after someone notices the jump.
- Any dashboard or report affected gets an annotation at the date of the change, not just
  a mention in a Slack thread that will scroll away.
- If a build's validation surfaces an unexpected jump, treat metric definition drift as a
  standing hypothesis — check `glossary/metric-definitions.md`'s last-updated date for
  every metric involved before looking elsewhere. See
  `templates/validation-checklist-template.md`.

---
type: policy
updated: 2026-07-06
---

# PII and Access Boundaries {#pii-and-access-boundaries}

External AI tools (Claude, ChatGPT, Cursor, Copilot, and similar) are useful for
clarifying requests, designing validation checks, and drafting summaries — see
`prompt-guides/`. None of that requires pasting a single real customer row into any of
them. This policy sets the boundary between what's safe to share and what isn't.

## Never paste into an external AI tool {#never-paste}

- Raw customer or account rows, exports, or spreadsheet excerpts containing real data.
- Personally identifiable information: names, emails, phone numbers, addresses, or any
  other field that identifies a real individual.
- Account-level detail tied to a real, identifiable company or person, even a single row
  "just to check the format."
- Credentials, API keys, connection strings, or anything that grants access to a system.
- Full unredacted query results, even if the query itself is safe to share.

This applies whether the tool is a chat interface, an IDE assistant with file context,
or an agent with tool access — the boundary is about what leaves your environment, not
which interface it leaves through.

## Safe to share {#safe-to-share}

- **Schemas** — table and column names, types, relationships. No data.
- **Aggregate numbers** — totals, counts, percentages, rates (e.g. "1,842 accounts",
  "MRR grew 4.2% month over month"). Aggregates that could uniquely identify an
  individual (e.g. "the one enterprise account in the Northeast region") are not safe —
  treat small-n aggregates as if they were row-level data.
- **Query and model logic** — SQL, dbt models, notebook cells, transformation code.
- **Synthetic or fictional examples** — made-up companies and numbers built to illustrate
  a pattern, clearly not real data (this pack's own Northwind examples are the model).
- **Metric definitions, clarified specs, and validation checklists** — these describe
  method, not data.

## Respecting access boundaries and least privilege {#respecting-access-boundaries}

- Only query data your role has access to. A clarified spec that requires data outside
  your access is an escalation, not a workaround — route it to whoever holds that access
  rather than requesting broader permissions "to be efficient."
  See `templates/clarified-spec-template.md`'s **Owner** field for who to route through.
- Don't grant an AI tool or agent standing access to a production warehouse or customer
  database. If a tool needs live query access, scope it to a read-only, non-PII view or
  a synthetic/staging dataset — never point it directly at raw customer tables.
  See `tool-guides/using-with-claude-code.md` for connecting this pack to an assistant
  safely.
- When in doubt about whether a field counts as PII, treat it as PII. Ask the team's
  data owner rather than guessing.

## If PII already reached a tool {#if-pii-already-reached-a-tool}

Treat it as an incident, not a cleanup task: stop the conversation, notify your team's
data owner or manager immediately, and follow your company's data incident process. Do
not try to quietly delete the message and move on — the exposure already happened
regardless of whether the message is later removed.

---
type: policy
updated: 2026-07-06
---

# Source of Truth Precedence {#source-of-truth-precedence}

Every metric in a clarified spec needs exactly one named source of truth — the system
whose number governs when two systems disagree. This policy sets the default precedence
rules and the process for when no default applies. See `glossary/source-of-truth.md` for
the definition and `templates/clarified-spec-template.md` for where you record the
choice on each request.

## Default precedence by metric family {#default-precedence-by-metric-family}

These are illustrative defaults for a company like Northwind, not universal law — your
team should adopt and publish its own list, then keep it current in this file or your
local overlay. The pattern matters more than the specific systems:

- **Revenue and billing metrics** (MRR, ARR, churn dollars) — the billing system wins
  over the CRM. The CRM reflects sales-stage estimates and manual edits; the billing
  system reflects what was actually invoiced or scheduled.
- **Usage and product metrics** (active accounts, feature adoption, session counts) —
  product analytics wins over spreadsheets or manually maintained trackers. Spreadsheets
  drift from the underlying event stream the moment someone forgets to refresh them.
  Product analytics wins over the CRM.
- **Account and org metadata** (plan tier, industry, employee count) — the system of
  record for that entity wins (e.g. the CRM for sales-owned fields, the billing system
  for plan and contract terms).
- **Support and CS metrics** (ticket volume, NPS, renewal risk) — the CS platform wins
  over ad hoc notes or Slack threads.

When two candidate sources are both plausible for the same metric, prefer the system
closer to the originating transaction over the system that summarizes or re-enters it.

## How to record a chosen source of truth {#how-to-record-a-chosen-source-of-truth}

Write the system name into the **Source of truth** field of
`templates/clarified-spec-template.md` for that request — not just "billing" but the
specific system (e.g. "Northwind Billing", not "finance"). If the choice required a
judgment call rather than following the default list above, note the reasoning in
**Open questions** or an inline comment so the next analyst doesn't have to re-derive it.

## When no authoritative source exists {#when-no-authoritative-source-exists}

Sometimes no system is authoritative yet — a new metric, a one-off analysis, or two
systems that both have partial claims. In that case:

1. Say so explicitly in the clarified spec rather than picking one silently.
2. Propose a source of truth to the stakeholder and get their sign-off before building —
   this is a decision, not a default.
3. Flag the metric as provisional in the insight summary's **Caveats & assumptions**
   field until a durable source of truth is established.
4. If the metric will recur, propose adding it to this file's default list so future
   requests don't repeat the ad hoc decision.

## Why this matters {#why-this-matters}

Contested numbers usually trace back to two people building against two different
systems, not to a math error. Naming the source of truth before building — and keeping
the default list current — prevents the argument from happening in the stakeholder
meeting instead of before it.

---
type: prompt-guide
updated: 2026-07-06
---

# Clarifying a Stakeholder Request {#clarifying-a-stakeholder-request}

Use an AI assistant (Claude, ChatGPT, Cursor, Copilot) to turn a vague request into a
complete draft of the clarified spec before you talk to the stakeholder. The assistant
is a drafting partner, not a decision-maker — it proposes fields and flags gaps; you and
the stakeholder confirm the values, especially source of truth and metric definition.
See `workflows/request-clarification.md` for the full clarify phase and
`templates/clarified-spec-template.md` for the fields this prompt fills in.

## Why prompt for this instead of just asking the stakeholder {#why-prompt-for-this}

Stakeholders describe outcomes, not specs ("how is MRR trending?"). An AI assistant is
good at turning that sentence into the full list of questions a spec requires, so you
walk into the clarifying conversation with a checklist instead of improvising it live.
It also catches missing fields you'd otherwise discover mid-build.

## What to paste in {#what-to-paste-in}

The stakeholder's request verbatim, plus any context you already have: who asked, what
channel, any decision they mentioned, and rough deadline. Do not paste raw customer data
or account-level detail — a one-line request rarely contains any, but if the stakeholder
pasted a spreadsheet excerpt into Slack, summarize it in your own words instead of
forwarding it. See `policies-and-rules/pii-and-access-boundaries.md`.

## Prompt scaffold {#prompt-scaffold}

```text
I received this stakeholder request and need to turn it into a clarified spec before
I build anything.

Request (verbatim): <paste exact wording>
Who asked / channel: <name/role, e.g. VP of Sales, via Slack>
Any context they gave: <optional>

Draft a clarified spec with these fields, using "unknown" for anything you cannot infer
and listing it under Open questions instead of guessing:

- Request (verbatim)
- Decision it informs
- Question (restated) -- a precise, answerable version of the ask
- Metric definition(s) -- name every metric and flag any ambiguous variant (e.g.
  committed vs. recognized revenue, trial vs. paid accounts)
- Source of truth -- the system whose number should govern; flag if more than one
  plausible system exists
- Grain -- aggregation level and row-level unit
- Filters / segments -- inclusions, exclusions, breakouts
- Time window -- exact range, rolling or fixed
- Acceptance criteria -- what "done" looks like, concretely
- Deadline
- Owner -- analyst and stakeholder contact
- Open questions -- everything still unresolved

Flag every field where you had to guess rather than infer directly from the request.
```

## After the model responds {#after-the-model-responds}

Treat the draft as a starting point for the clarifying conversation, not a finished
spec. The model cannot tell you which system is actually the source of truth at your
company, or what the stakeholder really meant by "trending" — those are decisions you
confirm with a human, then record in `templates/clarified-spec-template.md`. Do not
start building on any field still marked "unknown" if it affects the metric definition,
source of truth, or grain.

---
type: prompt-guide
updated: 2026-07-06
---

# Drafting an Insight Summary {#drafting-an-insight-summary}

Use an AI assistant to draft the prose of an insight summary from a validated result —
never to generate the result itself. By the time you reach this prompt, the build has
already passed validation (`workflows/build-and-validate.md`); the model's job is to
turn your numbers and notes into a clear, well-structured summary using the canonical
fields. See `templates/insight-summary-template.md` and `workflows/insight-delivery.md`.

## The analyst is the editor {#the-analyst-is-the-editor}

The model can draft a headline and phrase caveats cleanly. It cannot judge what the
result means for the decision, how confident to be, or which caveats actually matter —
those require knowing the business context and the stakeholder. Treat every draft as a
first pass you rewrite, not a final answer you forward. You own the headline answer, the
confidence rating, and the next action; the model only helps you say them well.

## What to paste in {#what-to-paste-in}

- The validated result as aggregate numbers (from `templates/validation-checklist-template.md`
  once every check has passed).
- The clarified spec's decision, metric definition, source of truth, and time window.
- Your own read on confidence and caveats — the model should refine these, not invent
  them from nothing.
- No raw data or row-level detail; see `policies-and-rules/pii-and-access-boundaries.md`.

## Prompt scaffold {#prompt-scaffold}

```text
Draft an insight summary from this validated result. I'll edit it, so favor precision
and brevity over polish.

Decision it informs: <e.g. quarterly board deck narrative on growth trajectory>
Question answered: <restated question from the clarified spec>
Validated numbers: <aggregate results, e.g. committed MRR by month, trailing 12 months>
Source / definition / window: <e.g. Northwind Billing, committed MRR, monthly, TTM>
My confidence and why: <e.g. High -- reconciled to finance control number within $0>
Known caveats or assumptions: <e.g. excludes accounts added after the 25th of the month>
Recommended next action: <e.g. include in board deck as-is; flag Q3 dip for discussion>

Structure the draft with these fields, in this order:
- Headline answer -- one sentence, no hedging language buried in it
- Confidence (High / Medium / Low) with one concrete reason
- Key numbers -- the smallest set that supports the headline
- What it means for the decision
- Caveats & assumptions
- Method (source, definition, window)
- Next action
- Links / appendix -- placeholder for the saved query and validation checklist

Keep the headline answer to one sentence. Do not soften the confidence rating with
qualifiers that aren't in "Caveats & assumptions."
```

## After the model responds {#after-the-model-responds}

Check the headline against the actual numbers — models drift toward optimistic framing.
Confirm the confidence rating is yours, not the model's guess at how confident you
should sound. Fill in `templates/insight-summary-template.md` with the edited draft, add
the real link to the saved query or notebook, and route through peer review before it
reaches the stakeholder.

---
type: prompt-guide
updated: 2026-07-06
---

# Validating a Build Against Source of Truth {#validating-a-build-against-sot}

Use an AI assistant to help design the validation checks for a build and reason about a
discrepancy — without ever pasting the underlying customer data into the tool. The
assistant is good at generating reconciliation queries and hypotheses for why two
numbers disagree; it does not need to see a single row of real data to do either. See
`workflows/build-and-validate.md` for the full validate phase and
`templates/validation-checklist-template.md` for the canonical checklist.

## The rule this prompt guide follows {#the-rule}

Never paste raw customer data, account-level detail, or row-level exports into an
external AI tool, even to ask "why doesn't this reconcile?" Aggregate numbers, schemas,
column names, query logic, and synthetic examples are safe to share. See
`policies-and-rules/pii-and-access-boundaries.md` for the full boundary and what
"aggregate" means in practice.

## What to paste in {#what-to-paste-in}

- The clarified spec's metric definition, source of truth, grain, filters, and time
  window (from `templates/clarified-spec-template.md`).
- Your query or model logic (SQL, dbt model, notebook cell) with table and column names
  — schema, not data.
- The control number from the source of truth and your build's total, as aggregate
  figures (e.g. "control: 1,842 accounts; build: 1,791 accounts").
- Never: customer names, emails, account IDs tied to real entities, or exported rows.

## Prompt scaffold — designing checks {#prompt-scaffold-designing-checks}

```text
I'm validating a build against a source-of-truth control number. Help me design the
reconciliation checks before I run them.

Metric definition: <e.g. committed MRR per billing system subscription schedule>
Source of truth: <system name>
Grain: <e.g. monthly, one row per account per month>
Filters / segments: <e.g. exclude internal test accounts>
My query logic (schema only, no data): <paste SQL/dbt/notebook snippet>

Walk through the canonical validation checklist and tell me, for each item, what
specific check I should run against this build:
- source of truth identified
- metric definition matches the agreed definition
- grain correct
- filters / segments applied correctly
- record counts reconcile
- totals reconcile to a source-of-truth control number
- sample rows spot-checked
- nulls & duplicates checked
- date boundaries / time zone correct
- result is reproducible
- peer reviewed

Flag anything in my query logic that looks like it could cause a mismatch (e.g. join
fan-out, timezone truncation, off-by-one date boundaries).
```

## Prompt scaffold — reconciling a discrepancy {#prompt-scaffold-reconciling-a-discrepancy}

```text
My build's total doesn't match the source-of-truth control number. Help me generate
hypotheses, using only these aggregate figures -- no raw data.

Control (source of truth): <aggregate number, e.g. 1,842 accounts>
Build result: <aggregate number, e.g. 1,791 accounts>
Difference: <e.g. -51 accounts, -2.8%>
Metric definition and filters in use: <paste>
Known recent changes: <e.g. upstream table added a new status value last week>

List the most likely causes ranked by probability (definition drift, filter mismatch,
grain mismatch, timezone/date-boundary issue, join fan-out or row loss, stale data), and
for each one tell me the specific aggregate check that would confirm or rule it out.
```

## After the model responds {#after-the-model-responds}

The assistant can narrow down where to look; it cannot confirm the fix without you
running the checks against real data yourself, inside your own environment. Once
reconciled, record what caused the discrepancy — if it was a metric definition change,
route it through `policies-and-rules/metric-change-control.md` so it doesn't silently
recur.

---
type: template
updated: 2026-07-06
---

# Clarified Spec Template {#clarified-spec-template}

## How to use this {#how-to-use-this}

Copy this file for every new stakeholder request and fill in each section before you
start building. If a field is genuinely unknown, write "unknown" and add it to
**Open questions** — do not leave it blank. See `workflows/request-clarification.md`
for how to run the clarifying conversation, and `examples/worked-example-mrr-request.md`
for a filled-in version of this template.

## Request (verbatim) {#request-verbatim}

The stakeholder's ask, copied exactly as they wrote or said it. Do not paraphrase here —
paraphrasing is where assumptions creep in.

_[e.g., "Can you send me a chart of how MRR is trending?" — from Slack, VP of Sales]_

## Decision it informs {#decision-it-informs}

What the stakeholder will do with the answer. If there's no decision attached, ask why
the request exists before building anything.

_[e.g., input to the quarterly board deck, narrative on growth trajectory]_

## Question (restated) {#question-restated}

The request rewritten as a precise, answerable question, in your own words.

_[e.g., "What has committed MRR done, by month, for the trailing 12 months, broken out by new / expansion / contraction / churn?"]_

## Metric definition(s) {#metric-definitions}

The exact definition of every metric involved, including which variant (e.g. committed
vs. recognized). Link to `glossary/metric-definitions.md` entries where they exist.

_[e.g., MRR = committed MRR per the billing system's subscription schedule, not recognized revenue]_

## Source of truth {#source-of-truth}

The single system whose numbers govern this metric. See
`policies-and-rules/source-of-truth-precedence.md` if two systems disagree.

_[e.g., billing system (Northwind Billing), not the CRM]_

## Grain {#grain}

The level of aggregation and the row-level unit the analysis is built from.

_[e.g., monthly, one row per account per month]_

## Filters / segments {#filters-segments}

Inclusion/exclusion rules and any breakouts the stakeholder needs.

_[e.g., exclude internal test accounts; segment by new / expansion / contraction / churn]_

## Time window {#time-window}

The exact date range, and whether it's rolling or fixed.

_[e.g., trailing 12 months, rolling, closed on the last completed month]_

## Acceptance criteria {#acceptance-criteria}

What "done" looks like, concretely enough that both you and the stakeholder would agree
the deliverable meets it.

_[e.g., monthly MRR total reconciles to the billing system's finance-blessed number within $0]_

## Deadline {#deadline}

When the stakeholder needs this, and whether that date is negotiable.

_[e.g., end of day Thursday, ahead of Friday's board prep review]_

## Owner {#owner}

Who is accountable for this request on the analytics side, and who the stakeholder
contact is.

_[e.g., analyst: you; stakeholder: VP of Sales]_

## Open questions {#open-questions}

Anything still unresolved. Do not start building with unresolved items that affect the
metric definition, source of truth, or grain — resolve those first.

_[e.g., does "trending" mean a line chart or a table? confirm with stakeholder]_

---
type: template
updated: 2026-07-06
---

# Insight Summary Template {#insight-summary-template}

## How to use this {#how-to-use-this}

Copy this file when you deliver a validated build to a stakeholder. Complete
`templates/validation-checklist-template.md` first — an insight summary reports on a
validated result, it does not replace validation. See `workflows/insight-delivery.md`
for the full deliver phase.

## Headline answer {#headline-answer}

The answer, in one sentence, before any supporting detail. Lead with this — a stakeholder
who reads nothing else should still get the answer.

_[e.g., "Committed MRR grew 4.2% month-over-month in June, driven by expansion revenue."]_

## Confidence {#confidence}

High / Medium / Low, plus one reason. Low confidence is a valid answer — say so rather
than hiding it behind precision the data doesn't support.

_[e.g., High — reconciled to the billing system's finance-blessed number within $0]_

## Key numbers {#key-numbers}

The 3-5 numbers that support the headline answer. Include the comparison point (prior
period, target, etc.), not just the raw figure.

_[e.g., June committed MRR: $1.42M (May: $1.36M); expansion: +$61K; churn: -$18K]_

## What it means for the decision {#what-it-means-for-the-decision}

Connect the numbers back to the decision from the clarified spec's "Decision it informs"
field. Do not make the reader do this translation themselves.

_[e.g., growth is expansion-led, not new-logo-led — relevant for the board narrative on pipeline health]_

## Caveats & assumptions {#caveats-assumptions}

Anything that could change the answer, or that a careful reader would ask about.

_[e.g., excludes accounts added after the 25th of the month due to billing system lag]_

## Method {#method}

Source, definition, and window, restated briefly so the summary stands alone.

_[e.g., source: Northwind Billing; definition: committed MRR; window: trailing 12 months, closed May]_

## Next action {#next-action}

What should happen next, and who owns it. An insight summary without a next action is
just a report.

_[e.g., include in Friday's board deck prep; flag expansion trend to CS-ops for renewal outreach]_

## Links / appendix {#links-appendix}

Links to the saved query/notebook, the validation checklist, and any supporting charts.

_[e.g., query: `queries/mrr-trend-2026-06.sql`; checklist: `validation/2026-06-mrr.md`]_

---
type: template
updated: 2026-07-06
---

# Validation Checklist Template {#validation-checklist-template}

Copy this checklist for every build before you deliver it. Work through all three
groups in order — definitions and scope come first because reconciliation against the
wrong definition just produces a confidently wrong number. See
`workflows/build-and-validate.md` for the full validate phase and
`policies-and-rules/source-of-truth-precedence.md` for resolving source conflicts.

Attach the completed checklist (or a link to it) to the deliverable — an insight
summary without an attached checklist has not been validated.

## Definitions & scope {#definitions-scope}

- [ ] Source of truth identified _[e.g., billing system confirmed, not the CRM]_
- [ ] Metric definition matches the agreed definition _[e.g., committed MRR, matches `glossary/metric-definitions.md`]_
- [ ] Grain correct _[e.g., one row per account per month, not per subscription line]_
- [ ] Filters / segments applied correctly _[e.g., internal test accounts excluded]_

## Reconciliation {#reconciliation}

- [ ] Record counts reconcile _[e.g., row count matches expected account count for the period]_
- [ ] Totals reconcile to a source-of-truth control number _[e.g., monthly MRR total matches billing system's finance-blessed figure]_
- [ ] Sample rows spot-checked _[e.g., 5 accounts traced by hand from source system to output]_
- [ ] Nulls & duplicates checked _[e.g., no unexpected NULLs in metric or key columns, no duplicate account-month rows]_
- [ ] Date boundaries / time zone correct _[e.g., month boundaries use billing system's close date, not UTC midnight]_

## Reproducibility & review {#reproducibility-review}

- [ ] Result is reproducible _[e.g., saved query or notebook, not a one-off scratchpad run]_
- [ ] Peer reviewed _[e.g., a second analyst re-ran the query and confirmed the totals]_

---
type: tool-guide
updated: 2026-07-06
---

# Using with ChatGPT {#using-with-chatgpt}

ChatGPT doesn't read a plugin manifest the way Claude Code does. Instead, you upload the
pack's files as knowledge so a project or custom GPT can search and cite them, then you
reference the specific file you want in your prompt.

## Upload the pack as project files {#upload-the-pack-as-project-files}

1. Create a ChatGPT project (or a custom GPT) dedicated to your team's analytics work.
2. Open the project's file upload area and add the markdown files from the pack. At a
   minimum, upload the four hero-workflow files and the three templates:
   `workflows/stakeholder-request-to-insight.md`, `workflows/request-clarification.md`,
   `workflows/build-and-validate.md`, `workflows/insight-delivery.md`,
   `templates/clarified-spec-template.md`, `templates/validation-checklist-template.md`,
   `templates/insight-summary-template.md`.
3. Upload the rest of the pack (`glossary/`, `policies-and-rules/`, `examples/`) as
   capacity allows — more files means better retrieval when you ask a specific question.

Keep the folder structure in the file names if your upload flow flattens directories
(e.g. rename a duplicate `README.md` to `glossary-source-of-truth.md`) so you can tell
files apart once they're all sitting in one project.

## Reference files in prompts {#reference-files-in-prompts}

ChatGPT's project files are retrieved by relevance, not loaded wholesale, so name the
file you mean instead of describing it vaguely:

```text
Using clarified-spec-template.md from the uploaded pack, help me clarify this stakeholder
request: "Can you send me a chart of how MRR is trending?"
```

```text
I've built the MRR query below. Walk it through validation-checklist-template.md and
tell me what's still unchecked.
```

Naming the exact template or workflow file gets you the actual field list from the pack
instead of ChatGPT improvising a generic checklist from its own training.

## Your first task {#your-first-task}

Upload at minimum `workflows/request-clarification.md` and
`templates/clarified-spec-template.md`, then run the canonical first request:

```text
A stakeholder (VP of Sales) asked: "How is MRR trending?" Using
request-clarification.md and clarified-spec-template.md from the uploaded files, ask me
the clarifying questions I need to answer before I build anything.
```

You should get back questions covering metric definition (committed vs. recognized),
source of truth, grain, segments, and time window — not a query. If ChatGPT jumps
straight to SQL, it didn't retrieve the uploaded files; re-check the upload and re-name
the file in your prompt.

## See also {#see-also}

- `../workflows/request-clarification.md`
- `../templates/clarified-spec-template.md`
- `../examples/worked-example-mrr-request.md`

---
type: tool-guide
updated: 2026-07-06
---

# Using with Claude Code {#using-with-claude-code}

This pack ships as a Claude Code plugin. Once installed, `SKILL.md` and every file it
routes to are available to Claude Code as project context — you don't paste anything in,
you just ask for the work and Claude Code reads the relevant pack files on its own.

## Install from the private marketplace {#install-from-the-private-marketplace}

If your organization has read-only collaborator access to the ContextCake Packs private
marketplace, add it and install the pack:

```bash
claude plugin marketplace add contextcake/contextcake-packs
claude plugin install data-analytics-team-pack
```

Collaborator access is read-only: you can pull updates but not push changes back to the
marketplace repo. To pick up a new release, run:

```bash
claude plugin marketplace update contextcake/contextcake-packs
claude plugin update data-analytics-team-pack
```

## Install from the unzipped files {#install-from-the-unzipped-files}

If you received the pack as a zip instead of marketplace access, unzip it anywhere on
disk and point Claude Code at the directory directly with `--plugin-dir` — no
marketplace registration needed:

```bash
unzip data-analytics-team-pack.zip -d ~/packs/data-analytics-team-pack
claude --plugin-dir ~/packs/data-analytics-team-pack
```

This loads the pack for that session. To load it every session in a given project, add
the same `--plugin-dir` flag to your project's Claude Code launch alias or wrapper
script.

## Where the files go {#where-the-files-go}

Whichever install path you use, the pack's directory structure is unchanged: `SKILL.md`
at the root, with `overview/`, `glossary/`, `workflows/`, `templates/`,
`policies-and-rules/`, `prompt-guides/`, `examples/`, and `tool-guides/` beneath it.
Claude Code reads `SKILL.md` first and follows its links into the rest of the pack as
needed — it does not load every file into context up front.

Do not edit files inside the installed plugin directory. If your team needs local
exceptions (a different source-of-truth system, a house style tweak), put them in your
own project context, not inside the pack. See `../local-overlay/README.md` for the
pattern.

## Your first task {#your-first-task}

Confirm the install worked by running the hero workflow on a real request. In a Claude
Code session inside your project, ask:

```text
A stakeholder wants to know how MRR is trending. Use the data-analytics-team-pack
workflow to help me clarify this request before I build anything.
```

Claude Code should pull in `workflows/request-clarification.md` and
`templates/clarified-spec-template.md`, then walk you through the clarified-spec fields
(source of truth, metric definition, grain, time window, and the rest) instead of
jumping straight to a query. That's the pack working correctly — clarify before build,
every time.

## See also {#see-also}

- `../SKILL.md`
- `../workflows/stakeholder-request-to-insight.md`
- `../updates/MERGE-GUIDE.md`

---
type: tool-guide
updated: 2026-07-06
---

# Using with GitHub Copilot {#using-with-github-copilot}

Copilot Chat draws context from files open or present in your workspace. There's no
plugin or upload step — the pack works as long as its files are checked into the
repository Copilot is attached to.

## Keep the pack files in the workspace {#keep-the-pack-files-in-the-workspace}

Add the pack to your repo, for example under `docs/`:

```bash
mkdir -p docs/data-analytics-team-pack
cp -R data-analytics-team-pack/* docs/data-analytics-team-pack/
git add docs/data-analytics-team-pack
```

Commit it like any other repo doc. Copilot's workspace-wide chat can then draw on it
without you opening every file by hand, though for anything specific — a template, a
workflow — you get more reliable results by opening the file or referencing it directly
(next section).

## Reference files in-chat {#reference-files-in-chat}

In Copilot Chat, use `#file` to attach a specific pack file to your question:

```text
#file:docs/data-analytics-team-pack/templates/insight-summary-template.md
Draft an insight summary for the MRR trend analysis I just finished, using this
template's fields.
```

```text
#file:docs/data-analytics-team-pack/policies-and-rules/source-of-truth-precedence.md
Our dashboard's active-accounts number jumped 20%. Does this policy tell me what to
check first?
```

If you're working in a file that already has the relevant template or workflow open in
another editor tab, Copilot Chat can pick it up from open tabs too — but `#file` is more
reliable when you need a specific document rather than whatever happens to be open.

## Your first task {#your-first-task}

Open `docs/data-analytics-team-pack/workflows/request-clarification.md` and
`docs/data-analytics-team-pack/templates/clarified-spec-template.md` as tabs, then ask
Copilot Chat:

```text
#file:docs/data-analytics-team-pack/workflows/request-clarification.md
#file:docs/data-analytics-team-pack/templates/clarified-spec-template.md
A stakeholder asked "How is MRR trending?" Use these to walk me through clarifying the
request before I write any SQL.
```

You should get the clarified-spec fields back as questions — metric definition, source
of truth, grain, time window, and the rest — not a query. If Copilot answers with SQL
directly, the pack files weren't actually attached; re-add them with `#file`.

## See also {#see-also}

- `../workflows/request-clarification.md`
- `../templates/insight-summary-template.md`
- `../updates/MERGE-GUIDE.md`

---
type: tool-guide
updated: 2026-07-06
---

# Using with Cursor {#using-with-cursor}

Cursor's assistant reads whatever is in your repo, so the fastest path is to check the
pack in as docs the assistant can pick up on its own — no separate upload step.

## Drop the pack into the repo {#drop-the-pack-into-the-repo}

Copy the pack directory into your project, typically under `docs/` so it reads clearly
as reference material rather than application code:

```bash
mkdir -p docs/data-analytics-team-pack
cp -R data-analytics-team-pack/* docs/data-analytics-team-pack/
```

If your team uses Cursor's project rules (`.cursor/rules/`), add a short rule that points
at the pack instead of duplicating its content:

```text
When helping with a stakeholder data request, follow the workflow in
docs/data-analytics-team-pack/workflows/stakeholder-request-to-insight.md and use the
templates in docs/data-analytics-team-pack/templates/.
```

This keeps the pack as the single source of truth for the workflow — the rule just tells
Cursor where to look.

## Reference files in-chat {#reference-files-in-chat}

Inside a Cursor chat, `@`-mention the file you want the assistant to read before it
answers:

```text
@docs/data-analytics-team-pack/templates/clarified-spec-template.md
Help me fill this in for a stakeholder request about MRR trending.
```

```text
@docs/data-analytics-team-pack/templates/validation-checklist-template.md
Check my query against this before I hand it off.
```

`@`-mentioning pulls the file into context explicitly, which matters for a pack like this
one — Cursor's implicit repo indexing is tuned for code, not for surfacing a markdown
template at the right moment.

## Your first task {#your-first-task}

Confirm the drop-in worked by clarifying the canonical example request. In a Cursor chat:

```text
@docs/data-analytics-team-pack/workflows/request-clarification.md
@docs/data-analytics-team-pack/templates/clarified-spec-template.md
A stakeholder asked "How is MRR trending?" Walk me through clarifying this request using
the linked workflow and template.
```

Expect Cursor to walk the clarified-spec fields — metric definition, source of truth,
grain, segments, time window, acceptance criteria — before proposing any SQL. If it
proposes a query first, the files weren't in context; re-mention them explicitly.

## See also {#see-also}

- `../workflows/request-clarification.md`
- `../templates/clarified-spec-template.md`
- `../updates/MERGE-GUIDE.md`

# Changelog

## 0.1.0 — 2026-07-06

Initial content release. The pack moves from OKF scaffold to full authored content:

- **Overview** — pack purpose, audience, and the one problem it solves
  (`overview/pack-purpose.md`).
- **Glossary** — six shared terms: source of truth, stakeholder request, clarified spec,
  metric definitions, validation pass, insight summary (`glossary/`).
- **Workflows** — the four-phase hero workflow (clarify, build, validate, deliver) plus
  its three phase-level breakouts: request clarification, build-and-validate, and
  insight delivery (`workflows/`).
- **Templates** — the clarified-spec, validation-checklist, and insight-summary
  templates used on every request (`templates/`).
- **Examples** — three worked examples, including the canonical Northwind MRR-trend
  request, grounding the templates in a full end-to-end request (`examples/`).
- **Prompt guides** — three guides for running pack workflows with an AI assistant in
  the loop, starting with clarifying a stakeholder request (`prompt-guides/`).
- **Policies** — three policies covering source-of-truth precedence and related
  change-control rules for when systems disagree or definitions shift
  (`policies-and-rules/`).
- **Tool guides** — four guides for using this pack with Claude Code, ChatGPT, Cursor,
  and GitHub Copilot (`tool-guides/`).

All examples use the fictional company Northwind; all figures are synthetic and
illustrative.

# Merge Guide

This pack updates roughly monthly. Because you should not edit installed pack files
directly (see `local-overlay/README.md`), updating means replacing the installed files
wholesale and re-applying anything your team keeps in its own overlay — not hand-editing
a diff.

For every update:

1. **Read `updates/CHANGELOG.md`.** Find the new version's entry and note which files or
   modules changed. Skip straight to step 4 if nothing in the entry affects a file you've
   overlaid or customized.
2. **Re-install or re-download the new version** of the pack (see the relevant guide in
   `tool-guides/` for your setup) rather than patching the old files in place.
3. **Diff the new pack files against your local overlay**, not against the old installed
   files. Your overlay is the thing you actually care about preserving; the old installed
   files are disposable. If you keep notes on which fields or sections you've overridden
   (a source-of-truth exception, an extra clarified-spec field, house terminology), check
   each one against the new version.
4. **Copy in the changes your team wants.** Most updates are additive (new glossary
   terms, a new example, a new tool guide) and need no action beyond re-installing. Only
   act on changes that touch a file or field you rely on.
5. **Keep local exceptions outside the installed pack files.** If a new version changed
   something your overlay depends on, update the overlay to match — do not fork the
   installed file. Forking defeats the next update.
6. **Re-run your first task.** After updating, re-run the tool guide's first-task check
   (see `tool-guides/`) to confirm your assistant is still picking up the pack correctly.

If a version bump is major (a new major version number in `updates/CHANGELOG.md`),
expect field names or file paths to have changed — read the changelog entry in full
before re-installing, since a straight overlay diff may not be enough.

---
type: workflow
updated: 2026-07-06
---

# Build and Validate {#build-and-validate}

Phases 2 and 3 of `workflows/stakeholder-request-to-insight.md`. Input: a signed-off
`templates/clarified-spec-template.md`. Output: a reconciled result plus a completed
`templates/validation-checklist-template.md`.

## Phase 2: Build {#phase-2-build}

Build strictly to the clarified spec — the metric definition, source, grain, filters, and
window you agreed with the stakeholder, not what's easiest to query.

**Northwind MRR example:** the clarified spec says committed MRR, billing system as source
of truth, monthly grain, segmented into new / expansion / contraction / churn, trailing 12
months. The analyst writes the extraction against the billing system's subscription
tables, not the CRM's opportunity records — the CRM tracks deals, not billed revenue, and
will not reconcile.

```sql
-- Committed MRR by month and movement segment, billing system as source of truth
select
  date_trunc('month', effective_date) as mrr_month,
  movement_segment, -- new / expansion / contraction / churn
  sum(committed_mrr_amount) as committed_mrr
from billing.subscription_mrr_ledger
where effective_date >= date_trunc('month', current_date) - interval '12 months'
group by 1, 2
order by 1, 2;
```

If the build surfaces a gap in the spec — say, annual contracts normalized inconsistently —
stop and go back to `workflows/request-clarification.md` rather than picking a convention
on your own and moving on.

## Phase 3: Validate {#phase-3-validate}

Validation reconciles your build to the source of truth named in the spec. Never deliver a
number that hasn't cleared this step. Use `templates/validation-checklist-template.md` and
consult `policies-and-rules/source-of-truth-precedence.md` whenever two systems disagree.

**Northwind MRR example, walked through the checklist:**

- **Source of truth identified:** billing system subscription ledger — confirmed in the
  clarified spec, not re-decided here.
- **Metric definition matches:** committed MRR, not recognized — check the ledger's
  `committed_mrr_amount` column, not a revenue-recognition column.
- **Grain correct:** one row per month per segment, matching the spec.
- **Filters/segments applied correctly:** new / expansion / contraction / churn sum to the
  same total as an unsegmented pull for the same month.
- **Record counts reconcile:** subscription row count for the month matches the billing
  system's own admin report count.
- **Totals reconcile to a control number:** finance publishes a blessed monthly MRR figure
  for board reporting — the build's total must match it within an agreed tolerance (for
  example, under 0.5%, attributable to rounding).
- **Sample rows spot-checked:** pull 5 accounts, verify their MRR contribution against the
  billing system UI directly.
- **Nulls & duplicates checked:** no subscription rows with a null `committed_mrr_amount`
  or duplicate `subscription_id` within a month.
- **Date boundaries / time zone correct:** month boundaries use the billing system's
  billing-cycle calendar, not UTC calendar months, if the two differ.
- **Result is reproducible:** the query is saved and versioned, not run ad hoc in a
  scratch tab.
- **Peer reviewed:** a second analyst re-runs the control-number check independently.

If the control-number check fails, do not adjust the build until it matches — find out
why. A mismatch usually means a wrong filter, a definition drift, or a genuinely stale
source; each has a different fix, and silently forcing a match hides the real problem.

## Output {#output}

A build that reconciles to the source of truth, plus a completed validation checklist
attached to the work. Proceed to `workflows/insight-delivery.md` only once every checklist
item passes or has a documented, agreed exception.

---
type: workflow
updated: 2026-07-06
---

# Insight Delivery {#insight-delivery}

Phase 4 of `workflows/stakeholder-request-to-insight.md`. Input: a validated result plus
completed `templates/validation-checklist-template.md`. Output: a filled
`templates/insight-summary-template.md` delivered to the stakeholder.

## Why a summary, not a screenshot {#why-a-summary-not-a-screenshot}

A dashboard screenshot or an unannotated link makes the stakeholder do the interpretation
work — and they'll do it without your context on caveats, definitions, or confidence. An
insight summary does the interpretation for them, states what's uncertain, and tells them
what to do next. That's the deliverable, not the query.

## Filling the summary {#filling-the-summary}

Use `templates/insight-summary-template.md` and cover every field:

- **Headline answer:** one sentence, in plain language, that answers the question restated
  in the clarified spec. "Committed MRR grew 4% month-over-month, driven by expansion" —
  not "here's the MRR data."
- **Confidence (High / Medium / Low + one reason):** state it explicitly. High means the
  validation checklist passed clean with no exceptions. Medium means it passed with a
  documented exception (for example, one system was a day stale). Low means you're
  delivering provisional numbers under time pressure — say so, don't hide it.
- **Key numbers:** the 3-5 numbers that matter, at the grain the stakeholder asked for. Not
  a full data dump.
- **What it means for the decision:** tie back to the "decision it informs" field from the
  clarified spec. If the board deck needs a growth narrative, say whether this number
  supports or complicates that narrative.
- **Caveats & assumptions:** anything a careful reader needs to know before repeating this
  number elsewhere — a normalization convention, an excluded segment, a known data gap.
- **Method (source · definition · window):** the three things most likely to make this
  number disagree with someone else's version of "MRR." Stating them prevents duplicate
  work and definition drift later.
- **Next action:** what should the stakeholder do with this? Approve a number for the
  deck, flag a segment for follow-up, decide nothing yet pending more data. A summary
  without a next action leaves the stakeholder guessing what you want from them.
- **Links / appendix:** the saved query, the validation checklist, and any supporting
  detail — kept out of the main summary so the headline stays readable.

## Stating confidence and caveats without hedging into uselessness {#stating-confidence-and-caveats}

State confidence and caveats plainly, but don't bury the answer under qualifications. One
confidence line and a short caveats list is enough. If you find yourself writing five
caveats, that's a signal the build or validation wasn't finished — go back to
`workflows/build-and-validate.md` rather than shipping a heavily caveated answer.

## Giving a next action {#giving-a-next-action}

Every summary ends with what happens next, addressed to a specific person where possible:
"VP of Sales: confirm this figure for the Q3 board deck by Thursday" beats "let me know if
you have questions." A next action turns a report into a decision point.

## Output {#output}

A filled `templates/insight-summary-template.md`, sent to the stakeholder named as owner in
the clarified spec, with the validation checklist linked as backup — not the primary
artifact.

---
type: workflow
updated: 2026-07-06
---

# Recurring Report Refresh {#recurring-report-refresh}

The loop for reports and dashboards you rebuild on a schedule — weekly, monthly, whatever
cadence the stakeholder needs. This is not a full re-run of
`workflows/stakeholder-request-to-insight.md` from Phase 1 each time. It's a lighter loop
that still protects against the two ways recurring reports quietly go wrong: definitions
drift, or upstream data changes underneath you.

## Why recurring reports need their own loop {#why-recurring-reports-need-their-own-loop}

A one-off request gets full clarification because the risk is understood once, up front. A
recurring report runs unattended for months — nobody re-reads the clarified spec every
Monday. That's exactly how definition drift and silent upstream changes reach a dashboard
unnoticed: the report keeps running, technically correct against last quarter's
assumptions, quietly wrong against this quarter's data.

## The refresh loop {#the-refresh-loop}

1. **Re-confirm definitions.** Before each refresh (or at minimum monthly for
   weekly reports), re-read the original `templates/clarified-spec-template.md` for this
   report. Confirm the metric definition, source of truth, and filters still match what's
   actually in the query. Specs don't self-update when a business definition changes.
2. **Watch for upstream metric changes.** Check whether any upstream system changed a field
   definition, a status flag, or a table schema since the last refresh. Upstream teams
   rarely broadcast this to analytics — you have to ask or watch for it. See
   `policies-and-rules/metric-change-control.md` for how changes should be requested and
   logged, and push back when a change lands without going through that process.
3. **Re-run the validation checklist.** Every refresh gets a full pass of
   `templates/validation-checklist-template.md` — record counts, control-number
   reconciliation, spot checks. A report that validated last month is not guaranteed to
   validate this month; treat each refresh as a new validation, not a rubber stamp.
4. **Deliver only if it reconciles.** If the checklist fails, do not publish the refresh on
   schedule. A late correct number beats an on-time wrong one. Flag the delay and the
   reason to the report owner.

## Worked example: active accounts jumps 20% {#worked-example-active-accounts-jumps-20-percent}

Northwind's weekly executive dashboard shows "active accounts" jumping about 20% week over
week — a swing far outside normal variance. Following the loop:

- **Re-confirm definitions:** the analyst checks the report's clarified spec — "active"
  was defined as paying accounts with a non-canceled subscription. The current query still
  matches that definition on paper.
- **Watch for upstream changes:** the analyst checks the source table and finds the
  `active` flag in the billing system was redefined last week to also include trial
  accounts, as part of an unrelated product change. Nobody notified analytics.
- **Re-run the validation checklist:** the control-number check fails — the new total
  doesn't reconcile against finance's paying-accounts figure, because trials are now mixed
  in.
- **Outcome:** the report is held, the upstream change is logged and routed through
  `policies-and-rules/metric-change-control.md`, and the query is either updated to exclude
  trials explicitly or the report is relabeled if the business now wants trials included.
  Either way, the decision is made deliberately, not inherited silently from an upstream
  flag change.

## Output {#output}

A refreshed, re-validated report delivered on schedule, or a documented hold with a
reason and an owner for the fix. Definition or upstream changes that affect the report get
logged via `policies-and-rules/metric-change-control.md`, not patched quietly in the query.

---
type: workflow
updated: 2026-07-06
---

# Request Clarification {#request-clarification}

Phase 1 of `workflows/stakeholder-request-to-insight.md`. Goal: turn a stakeholder
request (see `glossary/stakeholder-request.md`) into a written clarified spec (see
`glossary/clarified-spec.md`) that both sides agree on before any query is written.

## Why this phase exists {#why-this-phase-exists}

Most bad analytics work isn't a bad query — it's a correct answer to the wrong question.
"How is MRR trending?" can mean five different things depending on which MRR definition,
which source system, and which time window the stakeholder has in mind. Guessing any of
those wrong wastes a build cycle and erodes trust. Clarifying first is cheaper than
rebuilding later.

## Questions to ask {#questions-to-ask}

Work through the canonical clarified-spec fields. Don't skip a field because it seems
obvious — obvious to you is not the same as agreed with the stakeholder.

- **Request (verbatim):** What did they actually type or say? Capture it word for word
  before you paraphrase anything.
- **Decision it informs:** What will this answer be used for? A board deck, a headcount
  call, a one-off curiosity? This sets the bar for rigor and turnaround time.
- **Question (restated):** Play the question back in your own words and get confirmation.
  This alone catches half of all misunderstandings.
- **Metric definition(s):** For Northwind's "MRR," ask: committed or recognized? Does it
  include one-time fees? How are annual contracts normalized to monthly?
- **Source of truth:** Which system is authoritative — the billing system or the CRM? See
  `policies-and-rules/source-of-truth-precedence.md` if the stakeholder isn't sure.
- **Grain:** Monthly, weekly, daily? Per account, per segment, aggregate?
- **Filters / segments:** New, expansion, contraction, churn? Specific regions, plans, or
  customer tiers excluded or included?
- **Time window:** Trailing 12 months? Fiscal year to date? A specific quarter?
- **Acceptance criteria:** What does "answered" look like? A number, a chart, a trend line
  with commentary?
- **Deadline:** When is it needed, and is that a hard or soft date?
- **Owner:** Who on the stakeholder side can answer follow-up questions if something's
  ambiguous mid-build?
- **Open questions:** Anything still unresolved — log it rather than silently assuming.

## Pushing back on vague requests {#pushing-back-on-vague-requests}

A one-line Slack message is not a spec. When a request arrives underspecified:

- Don't start building "something reasonable" and hope it matches. Ask first.
- Offer a default and ask for confirmation rather than an open-ended question, when you
  can: "I'll use committed MRR from the billing system, monthly grain, trailing 12
  months — does that match what you need?" This is faster for the stakeholder to answer
  than a blank-page question.
- If the stakeholder pushes back on the clarification step itself ("just give me a
  number"), explain the cost of guessing wrong once, then hold the line — a five-minute
  conversation now is cheaper than a retracted number in a board deck.
- Escalate to a synchronous conversation (call, not chat) if written back-and-forth stalls
  after two rounds.

## Output {#output}

A filled `templates/clarified-spec-template.md`, shared back with the stakeholder for
explicit sign-off — not just sent and assumed read. Move to
`workflows/build-and-validate.md` only after sign-off.

---
type: workflow
updated: 2026-07-06
---

# Stakeholder Request to Insight {#stakeholder-request-to-insight}

This is the hero workflow of the pack: the path from a vague stakeholder question to a
trustworthy, delivered answer. It has four phases. Every request that reaches your team,
big or small, should move through all four — the depth you apply to each phase scales with
the stakes of the decision, but skipping a phase is how wrong numbers reach a board deck.

The running example throughout this pack: Northwind's VP of Sales asks "How is MRR
trending?" See `examples/worked-example-mrr-request.md` for the full walkthrough.

## The four phases {#the-four-phases}

1. **Clarify** — turn a vague stakeholder request into a written clarified spec.
2. **Build** — produce the query, model, or report against that spec.
3. **Validate** — reconcile the build to the source of truth.
4. **Deliver** — write an insight summary: answer, confidence, caveats, next action.

## Phase 1: Clarify {#phase-1-clarify}

**What happens:** You take the stakeholder's raw request — usually a Slack message or a
sentence in a meeting — and turn it into a written clarified spec covering metric
definition, source of truth, grain, filters, time window, acceptance criteria, deadline,
and owner. You do not start building until this is filled in and agreed.

**Who owns it:** The analyst who received the request, with the requesting stakeholder
answering questions. Neither side proceeds unilaterally — the analyst doesn't guess, the
stakeholder doesn't hand off and disappear.

**Artifact produced:** A filled `templates/clarified-spec-template.md`.

Full detail: `workflows/request-clarification.md`.

## Phase 2: Build {#phase-2-build}

**What happens:** You write the query or model strictly against the clarified spec — same
metric definition, same source, same grain, same filters, same window. No scope creep, no
"while I'm in here" additions. If the build reveals the spec was ambiguous or wrong, you
go back to Phase 1 rather than resolve the ambiguity silently in code.

**Who owns it:** The analyst or analytics engineer doing the work.

**Artifact produced:** A draft query, notebook, or model — not yet trusted, not yet shared.

## Phase 3: Validate {#phase-3-validate}

**What happens:** You reconcile the build's output against the source of truth identified
in the clarified spec: totals match a control number, record counts reconcile, a sample of
rows is spot-checked, nulls and duplicates are checked, date boundaries and time zones are
verified, and — for anything stakes-bearing — a peer reviews it. You do not deliver a
number you haven't reconciled.

**Who owns it:** The builder runs the checklist; a second team member peer-reviews before
anything goes external.

**Artifact produced:** A completed `templates/validation-checklist-template.md`.

Phases 2 and 3 in full detail, with the Northwind MRR reconciliation worked example:
`workflows/build-and-validate.md`.

## Phase 4: Deliver {#phase-4-deliver}

**What happens:** You turn the validated result into a written insight summary — headline
answer, confidence level with a reason, key numbers, what it means for the decision named
in the clarified spec, caveats, method, and a next action. You send the summary, not a raw
screenshot or an unannotated dashboard link.

**Who owns it:** The analyst who ran the work, reviewed by whoever owns the stakeholder
relationship if the result is going to leadership.

**Artifact produced:** A filled `templates/insight-summary-template.md`.

Full detail: `workflows/insight-delivery.md`.

## Recurring requests {#recurring-requests}

Reports and dashboards you rebuild on a schedule follow a variant of this loop rather than
starting from Phase 1 each time. See `workflows/recurring-report-refresh.md`.

## Reference {#reference}

- `templates/clarified-spec-template.md`
- `templates/validation-checklist-template.md`
- `templates/insight-summary-template.md`
- `policies-and-rules/source-of-truth-precedence.md`

id: data-analytics-team
name: "ContextCake Pack: Data & Analytics Teams"
version: "0.1.0"
creator:
  name: "ContextCake"
  url: "https://contextcake.com"
license:
  model: "personal-and-team"
  personal_price_usd: 99
  team_price_usd: 249
  team_seats: 5
  terms_url: "https://contextcake.com/packs/data-analytics-teams#license"
target_profession: "Data and analytics teams"
hero_workflow: "stakeholder request -> clarified spec -> build and validate -> insight summary"
sample_files:
  - examples/worked-example-mrr-request.md
  - templates/clarified-spec-template.md
changelog: updates/CHANGELOG.md
update_cadence: "monthly"
supported_surfaces:
  - plain-files
  - claude-code-plugin
  - chatgpt-knowledge-upload
  - cursor
  - copilot
required_reading_order:
  - overview/pack-purpose.md
  - workflows/stakeholder-request-to-insight.md
  - templates/clarified-spec-template.md
included_modules:
  - overview
  - glossary
  - workflows
  - templates
  - examples
  - prompt-guides
  - policies-and-rules
  - tool-guides
update_policy:
  cadence: "monthly"
  base_purchase: "perpetual"
  corrections: "included"
  editorial_updates: "optional-subscription"
  personal_monthly_usd: 9
source_disclosures:
  - "Original first-party workflows, templates, examples, and guidance authored for ContextCake."
rights:
  attested: true
  disclosure: "ContextCake owns or can commercially distribute every included item."
freshness:
  reviewed_at: "2026-07-17"
  review_interval_days: 90
permissions:
  content_only: true
  executable_code: false
  network_access: false
  credentials: false
compatibility:
  contextcake: ">=0.1.0"
  pack_contract: "1"
review:
  status: "first-party"
  reviewed_by: "ContextCake"
  reviewed_at: "2026-07-17"
artifact:
  checksum_algorithm: "sha256"
  checksum_scope: "canonical-content-tree"
  checksum: "pending-release"
overlay_instructions: "Keep local team overrides outside the installed pack files."

---
name: data-analytics-team-pack
description: Use when scoping a data request, validating a report or analysis against source-of-truth rules, or drafting an insight summary for stakeholders.
version: 0.1.0
---

# Data & Analytics Team Pack

This skill is an index over the pack documents. Do not restate the full workflows here —
read the linked file for the actual content.

## New request → clarify {#new-request-clarify}

- Start: `workflows/request-clarification.md`
- Fill in: `templates/clarified-spec-template.md`
- Prompting help: `prompt-guides/clarifying-a-stakeholder-request.md`
- Vocabulary: `glossary/stakeholder-request.md`, `glossary/clarified-spec.md`,
  `glossary/metric-definitions.md`

## Build → validate {#build-validate}

- Start: `workflows/build-and-validate.md`
- Fill in: `templates/validation-checklist-template.md`
- Precedence rules: `policies-and-rules/source-of-truth-precedence.md`
- Vocabulary: `glossary/source-of-truth.md`, `glossary/validation-pass.md`

## Deliver {#deliver}

- Start: `workflows/insight-delivery.md`
- Fill in: `templates/insight-summary-template.md`
- Vocabulary: `glossary/insight-summary.md`

## End-to-end reference {#end-to-end-reference}

- Full hero workflow: `workflows/stakeholder-request-to-insight.md`
- Worked example: `examples/worked-example-mrr-request.md`

## Policies {#policies}

- `policies-and-rules/source-of-truth-precedence.md`

## Tool setup {#tool-setup}

- `tool-guides/using-with-claude-code.md`
- `tool-guides/using-with-chatgpt.md`
- `tool-guides/using-with-cursor.md`
- `tool-guides/using-with-copilot.md`

## Glossary {#glossary}

- `glossary/source-of-truth.md`
- `glossary/stakeholder-request.md`
- `glossary/clarified-spec.md`
- `glossary/metric-definitions.md`
- `glossary/validation-pass.md`
- `glossary/insight-summary.md`

## First time here {#first-time-here}

New to the pack, or no AI assistant in the loop yet? Start at `START-HERE.md` instead of
this file.