# Funnel Report

Pull cross-funnel data via API, compute stage-to-stage conversion rates, and share a report file with the RevOps (Revenue Operations) team.

## When to use

- A scheduled or ad hoc request to report on funnel performance (leads to MQL to SQL to closed-won) arrives.
- RevOps asks for updated conversion rates or wants to see where the funnel is leaking.
- Before a pipeline review meeting, when a fresh snapshot of stage counts is needed.
- A stakeholder asks how a specific channel or campaign is converting through the funnel.

## Tools

- `http-get` — read stage-level data (leads, MQLs, SQLs, opportunities, closed-won) from the CRM (Customer Relationship Management system) and any connected marketing/analytics API.
- `shell-execute` — run a small script to aggregate stage counts and compute conversion rates and period-over-period deltas.
- `write-file` — save the finished funnel report (counts, conversion rates, commentary) to a file.
- `send-message` — notify RevOps that the report is ready, or escalate blockers.

## Playbook

1. Confirm the reporting window (e.g. last 30 days) and which funnel stages are in scope.
2. Call the CRM REST API with `http-get` (e.g. GET https://api.hubapi.com/crm/v3/objects/contacts) to pull lead and MQL (Marketing Qualified Lead) counts. 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. Call the CRM REST API with `http-get` again for SQL (Sales Qualified Lead), opportunity, and closed-won counts, using the same Integration-based authentication.
4. If a separate marketing or ads platform feeds the top of funnel, call that service's REST API with `http-get` under the same Integration rule to pull channel/campaign-level lead volume.
5. Use `shell-execute` to run a short script that joins the pulled data by stage, computes stage-to-stage conversion rates, and flags the largest drop-off point.
6. Use `shell-execute` to compute period-over-period change versus the prior comparable window, if historical data is available.
7. Use `write-file` to save the report (stage counts, conversion rates, biggest leak, notable channel trends) as a clearly named file.
8. If any stage's data looks incomplete or a required record needs correcting (not just reporting), do not attempt to write it back — compile the change list to a file with `write-file` and hand off to a human via `send-message`, since updating CRM records requires PATCH/PUT/DELETE access this skill does not have.
9. Use `send-message` to notify RevOps that the funnel report is ready, including the file location and a one-line summary of the key finding.

## Failure modes

- 401/403 response from any API call -> missing Integration; stop and escalate via `send-message` naming the service and required scopes.
- Empty or zero-count result for a stage -> verify the endpoint and query parameters before concluding the funnel is genuinely empty.
- Rate limit (429) response -> back off and retry later; note the limiting in memory so future runs pace requests accordingly.
- Source data schema or dashboard layout changed unexpectedly -> fall back to browser-search to confirm the current API structure before continuing.

## Done when

- A report file exists (via `write-file`) containing stage counts and computed conversion rates for the requested window.
- RevOps has been notified via `send-message` with the report location and headline finding.
- Any records needing correction were compiled into a handoff file rather than silently left inconsistent.