---
name: monthly-media-plan-status-report
description: "Build a client-facing monthly media-plan-versus-actual status report using the approved plan, media spend and CRM-only lead outcomes. Use for performance/status against plan, not internal agency margin. Resolve live workspace context and source bindings, expose unmapped/partial data, reconcile and prepare approved delivery."
---

# Monthly media-plan status report

**Version:** 1.1.0-rc.1. Reconstructed from supplied workflow specifications; this package's new
implementation is locally tested, not yet proven on a client. Runtime owns authority, access,
claims, schedule and email mechanics. This skill owns reporting meaning and validations only.

## Inputs and contract

Load [the input/output contract](references/report-contract.md). Resolve approved plan file/tab,
report period/timezone, media accounts, CRM label mappings, budget/targets, FX/currency, output
location and audience from live Context and tenant bindings. Do not infer account or source mappings.
If definitions conflict, preserve both source facts and hold that calculation, not all useful work.

## Workflow

1. Resolve the workspace and permitted action via runtime; identify this as client status, not
   agency profitability. Load the approved plan and bounded reporting window.
2. Collect required spend and activity through the canonical access owner. Use
   `crm-bmby-browser-reader` for Bmby data; do not duplicate its navigation here.
3. Preserve one coherent collection batch: one report window, per-source captured-at stamps and
   batch ID. Do not mix yesterday's pull with today's revised numbers. Record partial coverage.
4. Use only explicit approved CRM source mappings. Leads are CRM unique leads, never platform
   conversion counts. Platform conversions may be a separately labelled diagnostic only.
5. Reconcile source totals, correct hierarchy double-counting, dates, currency and plan scope.
   Unmapped labels stay visible/unresolved. Out-of-plan channels get a separate note, not silent
   inclusion in planned totals. Missing sources are not zero spend or zero leads.
6. Calculate normalized per-row metrics with `scripts/report_metrics.py`; source facts must be
   validated before this deterministic arithmetic. Undefined denominator returns null, never zero.
7. Generate the required report and warnings. Independently compare key values to sources and the
   approved baseline. A previously delivered defective report is never a golden fixture.
8. Hand report/message content to runtime for approved draft/send/update and provider read-back.
   Do not claim sent from a local file or draft. Return period, batch, coverage, location, validation
   and remaining gaps. Invoke approved reflective learning on reusable discoveries.

For an existing workbook, inspect actual MIME type; use native Sheets only for native documents.
Conversion creates a new file ID: verify content/permissions and update the binding through the
approved process. Preserve originals and history. Read the runtime's file-edit recovery guidance.