analyze-performance v0.1.1A

Immutable. This exact content never changes and is served at /api/v1/blob/efa8e31c04c4a7e6.

---
name: analyze-performance
description: >-
  Weekly performance read across every channel we run: what worked, why, and what to make next, judged
  on the business's real number (store revenue, qualified pipeline, retained users), not platform
  claims. Use when: write my Monday report; how are my ads doing — which ad won?; are my ads actually
  making money (Meta says 4x ROAS but revenue is flat); why did sales drop this week; did the test
  win; is my tracking working; monthly numbers for the replan; anything on fire today. Not for acting
  on the recommendations (pausing, scaling, launching) — use run-paid-campaigns; not for replanning
  the budget — use plan-campaign.
version: 0.1.1
---

# analyze-performance

## What you get

- **The Monday report** — saved to `reports/performance/<YYYY-MM-DD>.md` and shown in chat, the same shape every week (`references/monday-report.md`); run-paid-campaigns decides and acts on its recommendations.
- **Learnings** written to the brand brain after the marketer has seen and kept them; ended tests' measured results saved as readouts.
- **A run record** for next week (`references/run-memory.md`): the per-channel and per-ad scorecards with the trend since last run, each call with its owner, review date and test, and what happened to last week's calls — saved to the brand, so "what worked" and "what to make next" rest on weeks of history, not one week.
- **Monthly unit-economics read** for plan-campaign's replan; **daily pulse** on request, exception-only (`references/monthly-and-pulse.md`).

## Before you start

1. **Setup first:** do the `marketing-guide` skill (`../marketing-guide/SKILL.md`) §1–2 (connect, brand, brain read) before anything else; the job line is "read your results". This playbook offers **local mode** (marketing-guide §5): with no GooseWorks it reads through the marketer's connectors, else exports and screenshots, and keeps the contract, reports and run records in the local folder. A missing connection is never a blocker: say in one line what this read can and can't see, and go on.
2. **Read the brain and the plan** (free; local mode: `references/local-mode.md` instead). Brain chapters: 18 "How we count results", 20 "Our plan" (targets, decisions, experiments), 22 "Everything we have made and run", 23 "What is working" (readouts, worn-out angles, lessons). Fallback path: `brand_read` sections `summary, kit, products, learnings, onboarding, accounts`, and `knowledge_search` `["learning"]` for past results. Then `gooseworks:campaign_read` — live briefs (Economics, targets, Test plan, Measurement plan, Replan triggers, the change-log slug in Status); workspace (`gooseworks:file_list` / `file_read`): `reports/performance/definitions.md`, the latest dated report and its Decisions, `ads/campaigns/<slug>/state.md` (frontmatter `meta_push_ids`, health line, open recommendations) and the `### YYYY-MM-DD — <title>` blocks of `decisions.md` (what was actually done — written by run-paid-campaigns and the server), make-static-ads' batch files `ads/batches/<YYYY-MM-DD>-<slug>.md` (creative id → angle, hook, test; picks), `lifecycle/program.md` (which flows exist), the newest `research/competitors/watch/<YYYY-MM-DD>.md` (line 2), and research-market's "What people are saying" section — in the newest `research/market/<D>-read.md` (mentions, sentiment, trends, risks; check the section's own window line before treating it as this week's, and read share of voice only if it is there).
3. **Load the last runs** — the Start steps of the `run-memory` skill (`../run-memory/SKILL.md`) for this job (`weekly performance read`, `monthly read` or `daily pulse`; `references/run-memory.md`): the last record, plus up to four weekly records back for the scorecards and angle history; every earlier call checked against a source; run-paid-campaigns' newest run record for each campaign (its money moves and verdicts). No record → say it's the first read; this run's numbers become the baseline.
4. **Company type and referee** — `references/measurement-contract.md` §1. The type decides the referee, the ranking metric, the cadence (B2B under ~20 SQLs a month: weekly = leading indicators, pipeline monthly; services: monthly) and the inputs.
5. **One message, once; nothing asked mid-run.** Its contents and the export cheat sheet are `references/measurement-contract.md` §4 (minimum useful read first, history once, big exports in a hosted chat). Add what only this run knows: on the first run, the contract draft with defaults pre-filled (ask only the number and target, margin %, timezone — never technical settings), the roster to confirm, and which store, CRM, billing or analytics tool holds the referee unless the brain or a listed connector shows it (marketing-guide §3, "The marketer's own tools"; with none, that leg runs claims-only meanwhile); exports named in the last record's "Not checked" line, by name; the paid run's needs (`references/run-memory.md` § What the one input message also asks for). Missing items are "not checked this week"; a missing referee → **claims-only mode** (`references/measurement-contract.md` §5).

GooseWorks reads (connected only): `gooseworks:meta_read` performance view (Goose ads only, trailing windows ranked by spend — to identify Goose ads and cross-check, not as the week's totals); `gooseworks:social_account_list` + `gooseworks:social_analytics_get` (the brand's TikTok/Instagram accounts — other platforms come from the marketer); `gooseworks:ads_creative_read` (statics' lower-case tags, e.g. `angle:a-07`, `picked`; the batch file is the fallback when tags are missing) and `gooseworks:video_read` (videos' angle and hook names; a video without them is unannotated; an older `ads/videos/<project_id>.md` note is read only if it exists).

## Steps

**Route first.** "Anything on fire today?" → run Before you start 1–3, then only the pulse in `references/monthly-and-pulse.md` — no input message, no contract. "Monthly numbers / replan" (or the first Monday of the month) → add the customer-level store export to this week's one input message, run the weekly read, then the monthly read. Everything else → the weekly read below.

1. **Hygiene, maturity, coverage** — atom the `analyze-performance-intake` skill (`../analyze-performance-intake/SKILL.md`). On a first run, save the contract (confirmed, or as "draft — awaiting confirmation" if the marketer sent exports without confirming) to `definitions.md` and register it as a brand document through the `save-to-brain` skill (`../save-to-brain/SKILL.md`) (`versioned: supersede`); re-check the roster against the briefs and `state.md` and propose an amendment when a new channel appears. Strip test/wholesale/staff orders and renewals; net refunds; align timezones; equal-lag comparison; de-duplicate Goose ads against the export by ad id; save the input summary; write the coverage line over the roster.
2. **Business truth and the join** — atom the `analyze-performance-revenue-join` skill (`../analyze-performance-revenue-join/SKILL.md`), `references/revenue-join.md`. The type's referee vs last week, the 4-week average and the same week last year (or "vs plan only" for a new brand); for DTC: MER (labelled DTC MER when retail exists), new-customer MER, nCAC, contribution after ads vs break-even; the overclaim ratio on like-for-like terms; marginal vs average; budget pacing vs the month. When platform and blended disagree: both stories at the same grain, a recommendation, the cheapest settling test.
3. **Plumbing and the why** — atom the `analyze-performance-diagnose` skill (`../analyze-performance-diagnose/SKILL.md`), `references/diagnosis.md`. Plumbing first (breaks from the numbers, run-paid-campaigns' health line, and "measurement absent by design" with setup steps). Then, for every material move, the cause checklist with evidence, how sure, and ruled-out causes; light page/message match on the top winning and losing ads.
4. **Creative ranking and channel reads** — atom the `analyze-performance-rank-and-read` skill (`../analyze-performance-rank-and-read/SKILL.md`), `references/creative-and-channels.md`. Build the per-channel and per-ad scorecards against last run's rows (`references/run-memory.md` § Numbers). Angle → hook → format ranked by spend and judged on the type's business event (DTC: purchase CPA within the platform, claimed, capped at likely unless store new-customer orders moved with it); when only an upstream proxy exists (installs, leads, clicks), "cheap <event>, quality unknown" — no winner, no learning, "test" not "scale"; ads without a maker's angle annotation are "unannotated", never guessed from names. Then each rostered channel: email/SMS, organic, Google (+ wasted-spend terms), apps, local, B2B pipeline.
5. **Tests and recommendations** — atom the `analyze-performance-call-and-learn` skill (`../analyze-performance-call-and-learn/SKILL.md`), `references/tests-and-learnings.md`. Ended tests called against the brief's criteria; last week's calls scored through run-memory's outcome check (a money move run-paid-campaigns made: its verdict, plus this playbook's store-joined truth check over the same window); "what worked" only what held 2+ runs or won a test, "what to make next" from the history — tiring winners first, nothing that already failed (`references/run-memory.md`); this week's recommendations with how sure and "would change if" (the decision and the action are run-paid-campaigns'); fired replan triggers; the "what to make next" list; at most ~3 proposed learnings (n floors apply), each showing what it would retire.
6. **Write and show the report** — through the `write-report` skill (`../write-report/SKILL.md`), in `references/monday-report.md`'s shape (topic `performance-read`; brand copy `reports/performance/<YYYY-MM-DD>.md`, title `Performance read — <Brand> — <YYYY-MM-DD>`, tags `[analyze-performance, performance-read]`, `keep-history`). Its §3 checks, plus: labels per section (truth / claimed / derived); no platform revenue as truth; every rostered channel present; every call says how sure. Its Decisions for you is the **one decisions block**: which story to run on (if two), which learnings to keep or strike, any contract amendment, any re-test.
7. **On the marketer's reply** — re-save the report with a Decisions section; record the story pick in `definitions.md`; write the kept learnings through the `save-learning` skill (`../save-learning/SKILL.md`) (their words as the statement; one idea per learning; own superseded ones retired; say which landed). Nothing becomes a learning unless it appeared in a report the marketer saw. Measured readouts (ended tests called Win or Loss) are saved through save-learning's readout path, never from a scheduled run (`references/run-memory.md` § Experiment readouts).
8. **Save the run** — the End steps of the `run-memory` skill (`../run-memory/SKILL.md`): the record with the scorecards, the angle history line, this run's calls as recommendations (id, owner, review-by, how we'll know) and the outcomes of the last ones. Re-save it with the marketer's decisions when they reply. The daily pulse writes a pulse record (thresholds checked, breaks or "nothing").
9. **Monthly read** when routed above — `references/monthly-and-pulse.md`, with its own `monthly read` record (channel scorecard over the month vs the last monthly record).

## Approval gates

Nothing here is irreversible: this playbook reads and recommends; it never moves money, changes campaigns or publishes. Its judgment points end at the marketer:
- Which story to run the business on when platform and blended disagree.
- Whether a messy test result is enough to act on, or the test runs again.
- Learnings are written only from the marketer's own words after they have seen them.
- Kill/scale recommendations become real only when run-paid-campaigns decides on them, behind its money gate.
- Scheduling the report or pulse is offered once — a scheduled run uses credits, runs claims-only unless a connector exists, and should run before the paid run — and follows the `spend-gate` skill (`../spend-gate/SKILL.md`)'s automation rule (created paused, switched on by the marketer); the offer is recorded in `definitions.md` so it isn't repeated. Create it by marketing-guide §3 Schedules. With GooseWorks (`gooseworks:automation_upsert`): the method goes in `reports/performance/method/`, the prompt is `references/run-memory.md` § Setting up the schedule. Local mode: the host-scheduler branch there. Either way: read and report only; never apply, publish or spend.

## Output and write-back

- Workspace (brand coworker scope, `gooseworks:file_write`, re-read before writing; local mode: `references/local-mode.md`): `reports/performance/<YYYY-MM-DD>.md` (weekly — named for the Monday of the run week, kept when re-saved with Decisions), `reports/performance/monthly/<YYYY-MM>.md`, `reports/performance/inputs/<YYYY-MM-DD>.md`, `reports/performance/definitions.md`. The contract (`versioned: supersede`) and the monthly read (a period artifact, `keep-history`) are also registered as brand documents through the `save-to-brain` skill (`../save-to-brain/SKILL.md`).
- Run records `runs/analyze-performance/<job-slug>/<YYYY-MM-DD>.md` through run-memory (imported; read by its own next run and plan-campaign's replan). Experiment readouts (kind 23 `experiment_readout.*`) and, on the marketer's yes, worn-out angles (`worn_out_angle.*`) through save-learning.
- Learnings → the brand brain through the save-learning atom (read by every planner and maker; angle learnings start `[learning YYYY-MM-DD A-NN]` so research-competitors can update its bank).
- Who takes what: **run-paid-campaigns** — calls, plumbing flags, Google wasted-spend terms, the input summary · **plan-campaign** — weekly and monthly reads, fired replan triggers · **make-static-ads / make-content** — what to make next (a video item is offered as the next job with the goose-video skill) · **run-organic-social** — organic overperformers · **email-lifecycle** — the flow-and-send read · **improve-search-visibility** — the re-check nudge.

## Done when

On a brand with live spend and its store or CRM numbers provided, each rostered channel's winner, the why and the next-make are stated and grounded; platform revenue is never quoted as truth; learnings were written only from the marketer's words after they saw them. Without the referee it says plainly that it ran claims-only — the Done-when check needs the referee.

## Out of scope

- Applying any change (pausing, scaling, budgets, negatives) — run-paid-campaigns.
- Making the next creative — make-static-ads, make-content. Video ads: the goose-video skill.
- The monthly replan itself — plan-campaign (fed by this playbook).
- Fixing the pages it checks — not covered yet; the check here is read-only.
- Brand-search volume, share of voice, citations — research-market ("What people are saying"), improve-search-visibility (carried in when they exist).
- Standing alerts and watchers — not covered yet; the exception-only pulse covers the gap.
- The deep email flow audit — email-lifecycle; the organic content mix — run-organic-social.