Monthly Report

PREREQUISITE: Read ../_mureo-shared/SKILL.md for auth, security rules, output format, and Tool Selection (Read/Write on Code, mureo_strategy_* / mureo_state_* MCP on Desktop / Cowork).

Tool names below refer to the built-in platforms; a namespaced variant (see _mureo-shared → Namespaced built-in variants) is used with its prefix substituted.

Generate a client-facing monthly marketing operations report. This mirrors /weekly-report but over a calendar month, with month-over-month comparison, a goal-attainment verdict, and language written for the client/stakeholder who receives it — not internal shorthand.

Prerequisites

• STRATEGY.md with Goals (run the onboard skill first)
• STATE.json with action_log (actions must have been logged during the month)

Steps

Before you start: Run the Diagnostic preamble from ../_mureo-shared/SKILL.md — load learning insights (mureo_learning_insights_get) and consult advisors (mureo_consult_advisor) before drawing conclusions.

0. Establish today: call mureo_state_get first, on every host (including Claude Code, where you would otherwise Read the file) and take server_now from its response — ISO 8601 with UTC offset, e.g. 2026-07-28T10:12:33+09:00. Its date is the only source of the current date for this run, and this report is entirely calendar-driven: it decides which month is "the previous full month", the MTD cut-off date, the explicit YYYY-MM-DD..YYYY-MM-DD range you build for the month-before-last, and whether an observation_due window has closed. Do not shell out (this skill must run in Bash-less headless hosts) and do not read the date off STATE.json — last_synced_at, reports.*.period and action_log timestamps are history, never evidence of what day it is now; reporting a month late is exactly the failure this step prevents. Never write server_now into STATE.json: it is a response field, and a persisted copy becomes tomorrow's stale "today".
1. Load context: Read STRATEGY.md (Goals, Operation Mode, Persona, any ## Custom: Monthly Budget) and STATE.json (the same mureo_state_get response from step 0 on MCP hosts).
2. Discover platforms: Identify all configured platforms and available data sources — built-in, mcp__mureo__<plugin>_* plugin platforms, and any hosted official-MCP connector present in the session (e.g. TikTok's tt-ads-* tools, key tiktok_ads). See ../_mureo-shared/SKILL.md → Plugin platforms and Hosted-connector platforms; pull a hosted connector's numbers from its own reporting tools and omit mureo-only value-adds.
3. Reporting window: Default to the previous full calendar month — the month before server_now's month, named from server_now and never inferred from a stored reports.*.period. If the user explicitly asks for a mid-month / month-to-date view, use MTD instead — and state clearly at the top of the report which window it is (a partial month is not comparable to a full one).
   • Previous full month: Google Ads google_ads_performance_report with period="LAST_MONTH"; Meta Ads meta_ads_insights_report with period="last_month".
   • Month-to-date (only when explicitly asked): Google Ads period="THIS_MONTH"; Meta Ads period="this_month". Label it "MTD (through <date>)" — that date is server_now's date.
   • Native-preferred with official fallback: if mureo's Google Ads / Meta Ads tools are unavailable (MUREO_DISABLE_GOOGLE_ADS=1 / MUREO_DISABLE_META_ADS=1 after mureo providers add …-official), fall back to the official google-ads-official / meta-ads-official MCP over the equivalent window; note that mureo-only value-adds (result_indicator CV-mismatch) are absent from the official surface.
4. Month-over-month (MoM) comparison — the reporting month vs the month before it, using only windows the tools genuinely support (same honesty rule as the period above):
   • Meta Ads: meta_ads_insights_report supports an explicit 'YYYY-MM-DD..YYYY-MM-DD' range, so pull the month-before with its exact date range — computed by stepping back two months from server_now's month, not from any date found in STATE.json — and compare against last_month. A true Meta MoM is available.
   • Google Ads: google_ads_performance_report's period accepts an explicit range — period="YYYY-MM-DD..YYYY-MM-DD", the same form as Meta Ads (GAQL BETWEEN 'YYYY-MM-DD' AND 'YYYY-MM-DD' also works), both endpoints inclusive — alongside the date-range constants (#716). So pull the month-before with its exact first/last dates, computed by stepping back two months from server_now's month and never from a date found in STATE.json, and compare against LAST_MONTH. A true Google Ads MoM is available. If the explicit-range call fails, fall back in order to (a) STATE.json's persisted prior-month rollup (platforms[<p>].periods[...]) or the previous monthly report's kpis (from mureo_state_report_set history); (b) state that the Google Ads MoM comparison is unavailable this month rather than mislabel LAST_90_DAYS (a 3-month blend) as "the prior month". Never silently substitute a different window.
   • Show MoM change (absolute and %) for spend, conversions, CPA, and CTR per platform.
   • Auth failure is not data — it is a hole in the report. Any tool result carrying "status": "auth_error" in steps 3–4 means mureo could not read that platform for this month at all: auth_cause is no_credentials (nothing is configured) or token_invalid (a credential exists and the platform rejected it — typically an expired token), and detail is the operator-facing sentence. Never render detail where a metric belongs, and never read that platform's missing or empty numbers as "quiet" — unreadable and quiet are different facts. Record the platform name with its auth_cause and carry both into steps 11, 12 and 14, then keep going for every other platform: one platform's credentials failing degrades the report, it never aborts the run.
   • A partial month is not comparable to a complete one — the same rule the MTD window already carries in step 3, and it bites harder here. A platform that answered auth_error contributes nothing to either month — the same credential failed both pulls — so its MoM line is unknown, not flat and not a decline: render it as unread with its auth_cause, never as 0, never as -100%, never as a blank cell a reader fills in as zero. The baseline in (a) is the sharp edge: STATE.json's persisted rollup and the previous monthly report's kpis were written when that platform was readable, so a MoM built from them sets a month missing a platform against a month that had it and manufactures a decline out of a credential problem — in a document a client reads. Either restate both months over the same set of platforms that answered this month, labelling the total with that set, or withhold the comparison and name the platform whose absence blocks it. Never silently substitute a differently-scoped figure.
5. Goal attainment summary (the month): For each Goal in STRATEGY.md, gather the month's metric from the relevant platforms / data sources and render a met / missed / partial verdict with the numbers:

   Goal: CPA < 5,000        -- Met      (Google 4,600 / Meta 4,900; blended 4,720)
   Goal: CV >= 100/month    -- Partial  (Google 71 / Meta 24; total 95, 95% of target)
   Goal: Organic clicks +20% -- Missed  (Search Console +11%)

6. Actions taken — month recap grouped by command: read action_log, filter to the reporting month, and group by the command / skill that produced each entry (daily-check, budget-rebalance, rescue, creative-refresh, budget-pacing, …). For each group summarize what was done and how often:

   Command

   # actions

   What changed

   Platforms

7. Outcome verdicts (evidence pipeline): for action_log entries whose observation_due window closed within or before this month, call mureo_outcome_evaluate with evaluation_of = the entry's index and after = the campaign's metrics object from mureo_state_get, unchanged (including period and fetched_at) (pass before only when the entry recorded no metrics_at_action (beside one it is refused: evaluation_of_conflicts_with_before)) — it returns a deterministic improved / regressed / inconclusive verdict on one primary metric, with every other metric as a reference row; an inconclusive one carries a reason (insufficient_volume means not yet measurable). For an entry that is still open (no later evaluation_of record), then append the evaluation record via mureo_state_action_log_append: evaluation_of = the same index, evaluation = the evaluation object the tool returned, exactly as returned, and action = "Outcome evaluated" (a neutral label — the table carries the verdict, so do not restate it in action; do not pass summary — mureo builds it from the table). Report each action's outcome with the confidence it implies (low: <1 period, medium: 1 period, high: 2+ consistent periods). For entries still within their observation window, list them as "pending — not yet conclusive" and do not present them as wins. Normalize any hosted-connector / plugin metric names to the standard keys (cpa, conversions, ctr, cost, …) before scoring. When summing Meta "results" across campaigns, group by result_indicator — never aggregate link_click totals with offsite_conversion.fb_pixel_lead totals (PR #61).
8. Budget utilization: if a ## Custom: Monthly Budget section exists in STRATEGY.md, compare actual month spend vs the monthly target (total and per-platform sub-targets) and report utilization %. Cross-link /budget-pacing for the in-month trajectory view and for landing-forecast mechanics. If no Monthly Budget section exists, report actual spend per platform and note that no monthly target is configured.
9. Cross-platform insights: compare the month's efficiency across platforms (CPA, CVR, ROAS); call out which platform gained or lost efficiency MoM; if Search Console is available, include the organic search trend (clicks, impressions, CTR MoM) and paid/organic overlap shifts; suggest cross-platform shifts if one platform is clearly outperforming toward Goal achievement.
10. Next-month recommendations:
    • Based on Goal trajectory, name the focus areas for next month.
    • Recommend specific commands to run (/rescue, /budget-rebalance, /budget-pacing, /creative-refresh, /goal-review).
    • Operation Mode suggestion: recommend a mode for next month if the data supports a change (e.g. "Goals met and stable — consider TURNAROUND_RESCUE → EFFICIENCY_STABILIZE"), with the reason.
11. Executive summary — written for the CLIENT: lead the report with a 3-5 sentence executive summary in plain language for an agency's client audience. No internal jargon, no tool names, no mode codenames — translate them ("we tightened targeting to protect your cost-per-lead", not "ran /rescue, switched to TURNAROUND_RESCUE"). State the headline result, whether goals were met, and the one thing to watch next month.

12. Present the report in a structured, shareable layout:

    Partial report — this goes FIRST, above the executive summary. If any platform came back "status": "auth_error" in steps 3–4, this report is partial: open it by saying so, naming each affected platform with its auth_cause and the recovery (no_credentials → configure the credential via mureo configure / mureo auth setup; token_invalid → re-authorize, the credential is present and dead). Say it in the client's language too — "we could not read <platform> this month, so its figures are missing rather than zero" — since the step-11 summary is written for a non-technical reader who will otherwise take the gap for a result. Then withhold every goal-attainment verdict, MoM comparison, budget-utilization line and recommendation that depends on that platform's numbers — an unreadable platform has no performance to judge, and cross-platform advice (budget shifts, "scale here, cut there") derived only from the platforms that did answer is not the advice you would give with all of them. Report the platforms that did answer as usual, and make clear which is which.

    • Executive summary (client-facing, plain language)
    • Reporting window (and whether full-month or MTD)
    • Goal attainment table (met / missed / partial)
    • Cross-platform performance with MoM comparison
    • Key actions and their outcomes (with confidence level)
    • Budget utilization (if a Monthly Budget is configured)
    • Recommendations for next month

    This report is read-only — it never mutates platform state. If a recommendation calls for a change, run the relevant skill (/rescue, /budget-rebalance, /budget-pacing), which applies its own approval gate and confirms with the operator before any write; monthly-report itself only reads and summarizes.

13. Log to action_log (via mureo_state_action_log_append) that a monthly report was generated, including the reporting month. Give every entry a display line: display_title (at most 40 characters) and display_summary (at most 120) — what this action WAS, in the operator's words, as plain text with no markdown (**bold** reaches a person as asterisks). The dashboard row shows those two and stops there; the full summary is drill-down only, so keep writing it as fully as the next agent needs and let the display line be the short one. Over either bound the append is refused, never truncated.

14. Persist the report summary (best-effort): Call mureo_state_report_set with report="monthly" and a concise summary object so the read-only dashboard can render this report without re-running you. Follow this convention:

    • generated_at: ISO 8601 timestamp of this run — use server_now
    • period: the reporting month (e.g. "2026-06"), and whether full-month or MTD
    • totals: the account's headline figures, using the canonical metric vocabulary — spend, conversions, cpa, ctr, clicks, impressions. This is the block the dashboard renders as figures. Raw numbers only: 773957, not "¥773,957"; 0.0466, not "4.66%" — one of those keys carrying a string is refused, because it sits where the view reads a figure and renders as nothing. A key outside the vocabulary may ride along: it is stored, just not shown as a headline number. Omit totals entirely if this run gathered no account-level figures.
    • kpis: the per-platform split (spend, conversions, cpa, MoM change) — the breakdown, not the headline row
    • flags: notable items (e.g. ["cv_goal_missed", "meta_cpa_up_12pct_mom"])
    • narrative: the client-facing executive summary in plain language — the verdict and what you propose next, at most 400 characters — the tool refuses a longer one rather than truncating it (a sentence cut in half is worse than a long one). Do not restate the figures and do not list the findings here: numbers belong in totals, findings in flags.

    Never persist a number you did not read. For a platform that came back "status": "auth_error", omit its kpis entry entirely rather than writing 0 — step 4(a) reads this rollup as NEXT month's MoM baseline, so a fabricated zero turns one month's credential problem into two months of phantom movement. Omit it from the blended totals too, or label those totals with the platforms they cover. Add a flag naming the partial read (e.g. "partial_read_<platform>_<auth_cause>") and say so in narrative.

    Reflect the FINAL state, and persist this LAST. This is best-effort: if mureo_state_report_set is unavailable (e.g. a pure file-mode host without the context MCP), skip it silently — the rest of this skill still works.

15. Persist the display contract (best-effort): Call mureo_state_display_set with what the DASHBOARD shows. This is a different audience from the summary above — STATE.json is written for the next agent, and this small bounded section is the only thing the operator's screen reads. Write it in the SAME pass as the report, from the SAME figures, and reach no new verdict here: every value below is one you already decided, and this step only renders it.

    • source: your own skill name — REQUIRED whenever you write any section, at most 24 characters. The contract is replaced wholesale by whoever writes it last, so this is what lets the card say whose answer it is showing. generated_at is stamped by the server — do not compute it.
    • nav_message: the ONE line the operator should act on today — what next month turns on, e.g. "CPA improved 14% MoM — reinvest the saving in Brand Search". One line, not a summary of the report.
    • highlights: at most 3 chips, and the tone must match the verdict you already gave — good for a target met or a clear win, watch for something to keep an eye on, bad for something deteriorating. Choose the three that matter; a fourth is refused and nothing is dropped for you. Map a finding's severity to a chip tone: action → bad / watch → watch / positive → good. info does NOT become a highlight — a neutral note would spend one of the 3 chips an action or a win needed, and it is still in the report for whoever wants it.
    • breakdown.campaigns / .adgroups: one row per entity you judged, carrying figures you ALREADY hold — spend, mcpa (the measured CPA) and target_cpa — plus state from the closed set (target_met / improving / watch / worsening / no_data) and a note of at most 40 characters. Use campaigns for the month's campaigns and adgroups where you broke the month down that far. Omit a figure you do not have: 0 states a perfect CPA rather than the absence of one, and no_data is the state for an entity with too little delivery to judge.
    • proposals: the recommendations you did NOT carry out, one entry each — title (what to do) plus body (why, in one line) plus date = server_now's date as YYYY-MM-DD. Something you DID apply this run is the same entry with status: "done".
    • stated_values: label + figure chips ONLY ({"label": "…", "value": …}) — the month's headline comparisons: {"label": "MoM CPA", "value": "-14%"}, {"label": "goals met", "value": "3 of 4"}. No prose notes here. A sentence lands in a numeric column and the tool refuses it; anything that needs a sentence stays in the report's narrative above, exactly where it goes today.

    The bounds, verbatim from the tool: The dashboard reads THIS section and nothing else — keep your reasoning where it already goes. Every bound below refuses the write rather than truncating it, because a sentence cut in half is worse than a long one. nav_message: one line, at most 80 characters. highlights: at most 3 items of {tone, text}, tone one of good/watch/bad, text at most 60 characters. proposals: {title, body, status, date}, title at most 30 and body at most 80 characters, status one of proposed/done. breakdown.campaigns / breakdown.adgroups: rows of {name, spend, mcpa, target_cpa, state, note} — the three figures are raw numbers, state is one of target_met/improving/watch/worsening/no_data, note at most 40 characters. stated_values: {label, value}, label at most 24 characters and value a raw number or a string of at most 12 characters — a sentence there is refused, because it lands in a numeric column. Do NOT write the KPI funnel or the daily chart: mureo computes both from the stored totals.

    Over a bound the write is REFUSED — shorten and rewrite, do not re-send the same sentence trimmed. Lead with the point and drop the connectives; a noun phrase is fine (CPA 12% over target, not The CPA is currently running about 12% above the target we agreed). Trimming one character at a time and calling again spends the run's context on a bound one rewrite would have met.

    You may not be the first writer today. display is REPLACED WHOLE and the last writer wins — there is no merge. Before you write it, read the current one (mureo_state_get). Of what another skill wrote TODAY, carry exactly one thing into your own write: its proposals that are still live — not yet done, and not contradicted by what you just found. Everything else you write from your own run alone, because a screen assembled from two runs shows a moment that never happened. And carry over NOTHING ELSE: never copy another skill's nav_message, highlights, breakdown or stated_values, which would put its judgement under your name when you cannot vouch for it. Name yourself in source so the screen says whose answer it is.

    This is best-effort: if mureo_state_display_set is unavailable (e.g. a pure file-mode host without the context MCP), skip it silently — the rest of this skill still works.