# Engagement Report

Pull social media engagement metrics from a connected platform API, compute period-over-period results, and share a report file with the team.

## When to use

- A teammate asks for likes/comments/shares/reach numbers for a campaign or date range.
- A recurring cadence (weekly/monthly) requires a fresh engagement summary.
- Leadership needs a quick read on which posts or channels are over/underperforming.
- Someone requests a comparison of engagement across accounts or time windows.

## Tools

- `http-get`: retrieve engagement metrics (likes, comments, shares, reach, impressions) from the social platform's REST API.
- `shell-execute`: run a small script to aggregate, dedupe, and compute period-over-period metric math on the pulled data.
- `write-file`: save the computed report as a file (e.g. markdown or CSV) for the team.
- `send-message`: notify the requesting human or another agent that the report is ready, and escalate any blockers.

## Playbook

1. Confirm the request scope: platform(s), account(s), date range, and which metrics matter (likes, comments, shares, reach, impressions).
2. Call the social platform REST API with `http-get` (e.g. GET https://graph.facebook.com/v19.0/{page-id}/insights). 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 multiple accounts or date ranges are needed, repeat step 2 with `http-get` for each page/endpoint, paginating until all results for the window are collected.
4. Use `shell-execute` to parse the raw JSON responses, normalize field names across accounts, and merge into a single dataset.
5. Use `shell-execute` to compute totals, averages, and period-over-period deltas (e.g. this week vs last week) for each metric.
6. Use `shell-execute` to identify top and bottom performing posts by engagement rate, flagging any outliers worth calling out.
7. Draft the report body (summary, key numbers, top/bottom posts, notable trends) and save it with `write-file` to a clearly named report file.
8. If any requested change to the underlying data (e.g. correcting a post's metadata via PATCH/PUT/DELETE) is needed, this is NOT possible with the declared tools — compile the change list into the report file via `write-file` and hand off to a human via `send-message` rather than attempting it.
9. Notify the requester via `send-message` that the report file is ready, including its location and a one-line summary of the headline finding.

## Failure modes

- API call returns 401/403 -> missing Integration; stop and escalate via `send-message` naming the service and required scopes.
- Empty or near-empty result set -> verify the endpoint URL, account ID, and date-range parameters before re-querying.
- Rate limit hit -> back off and retry later; note the limit and timing in memory so future runs pace requests accordingly.
- Platform page/API structure changed and results look malformed -> fall back to browser-search to confirm current endpoint documentation before retrying.

## Done when

- A report file exists (via `write-file`) containing computed engagement totals, deltas, and top/bottom performers for the requested scope.
- The requester or team has been notified via `send-message` with the report location and headline summary.
- Any data-correction needs beyond read access are documented in the report and explicitly routed to a human, not silently skipped.