# Metric Digest

Pull marketing metrics from a connected SaaS API, compute the key numbers, write a digest file, and notify the stakeholders who need to see it.

## When to use

- A recurring or ad hoc request to summarize campaign, traffic, or funnel metrics for a given period.
- Someone asks "how did we do this week/month" for a specific channel or platform.
- A stakeholder needs a digest file delivered before a review or standup.
- After a metrics source is connected and a baseline digest is needed to validate the integration.

## Tools

- `http-get` — read metrics from the connected analytics/marketing SaaS API (e.g. campaign stats, traffic totals, funnel counts).
- `shell-execute` — run a small script to aggregate, dedupe, and compute derived numbers (rates, deltas, totals) from the raw API response.
- `write-file` — write the finished digest as a markdown or CSV file.
- `send-message` — notify stakeholders in-session that the digest is ready, or escalate blockers to a human.

## Playbook

1. Confirm the metrics source, the reporting period, and which numbers the stakeholder cares about (e.g. sessions, conversions, spend, CTR).
2. Call the metrics REST API with `http-get` (e.g. GET https://api.<service>.com/v1/reports). Authentication is injected by the org's Integration row for this host — never ask for, echo, or hardcode credentials. If the call returns 401/403 or no Integration row exists, stop and message a human via `send-message` asking them to create the Integration, naming the service and required scopes.
3. If the period requires multiple pages or date ranges, repeat step 2 with `http-get` until all raw data is collected.
4. Save the raw API response to a working file with `write-file` so the computation step has stable input.
5. Use `shell-execute` to run a short script that parses the raw file, computes totals, rates, and period-over-period deltas, and flags anomalies.
6. Draft the digest as a clear markdown summary: headline numbers first, then a short table, then notable changes or anomalies.
7. Write the finished digest to a file with `write-file`, using a clear filename that includes the metric scope and period.
8. Notify the relevant stakeholders that the digest is ready with `send-message`, including the headline numbers inline and a pointer to the file.
9. If any number looks implausible (e.g. zero traffic, negative spend) do not report it as fact — flag it explicitly in the digest and in the `send-message` notification as needing verification.

## Failure modes

- 401/403 on the API call -> missing Integration; stop and escalate via `send-message` naming the service and required scopes.
- Empty or zero-value result -> verify the endpoint, date range, and filter parameters before trusting the number; retry with corrected params.
- Rate limit (429) hit during pagination -> back off, wait, and note the rate limit in memory so future runs pace requests accordingly.
- API only supports read access but the request implies updating a report or record -> that requires PATCH/PUT/DELETE, which is NOT POSSIBLE with these tools; compile the intended change and hand off to a human via `send-message`.

## Done when

- A digest file exists (written via `write-file`) containing computed metrics, deltas, and any flagged anomalies for the requested period.
- Stakeholders have been notified via `send-message` that the digest is ready, with headline numbers included.
- Any data quality concerns or blocked updates are explicitly flagged rather than silently omitted.