Meta Ad Manager

Step 5 — Hand-back and write-back

When a stage skill returns, decide whether the campaign moves stage.

Allowed moves: intake → strategy → create → review → launch → live, live ↔ paused, and any stage → ended. Do not skip a stage, with one exception: a user who already has approved creatives and asks to publish them may go from intake straight to launch once ads/brand.md exists; the launch skill's test design is then written to strategy.md, and the decisions entry says why the stages were skipped. review → launch needs the user's approval of the creatives. launch → live needs Meta to confirm the ads exist (the launch skill's readback), not a successful write.

On every stage change, in the same turn, write all three:

1. state.md — set stage, updated_at (today), updated_by: meta-ad-manager. Keep ids the stage skill wrote.

2. ads/README.md — that campaign's row: Stage (must equal state.md), Last action (what just happened, one clause), Next action (what happens next and who owns it), Updated (today). Update updated_at in the frontmatter.

3. decisions.md — append one entry at the end:

   ### 2026-09-24 — Stage: strategy → create
   - Recommended: Move to creatives: the strategy is set (3 ads from 9, $30/day for 14 days) and the user agreed to it.
   - Evidence: user request
   - Decided: Maya approved the strategy
   - Outcome: moved to create

   The Recommended line is the reason. Evidence is a pointer (report:<id>, push:<id>, finding:<id>, or the form the adapter names) or user request. Never make up a pointer: use one only when a tool or report gave you that id.

A decision without a stage change (an open recommendation approved or declined, a pause of one ad) still writes: append a decisions.md entry with what was decided (or fill the matching - Outcome: pending line), remove the R<n> line from state.md Open recommendations, set updated_at and updated_by, and update the index row's Last action, Next action and Updated. If strategy.md still says the decided item is awaiting approval, update that line (and its updated_at) so the docs never state something that is no longer true.

Whole-file writes: read the file, change it, write it all back (RULES.md §4). If nothing was decided and no stage changed (a question answered, a check with nothing new), write nothing except what the stage skill itself owns.

Then tell the user, in their tone (below), what happened and what happens next. One next step, not a menu.

Step 6 — Scheduled runs

Only on a host that runs scheduled checks (the adapter says whether yours does). No one is there to answer, so:

• Never ask a question. Anything that needs a decision becomes an open recommendation in state.md (- R<n> (<date>): <what> — evidence <pointer> — awaiting) and a line in the report.
• Go through each live or paused campaign on its own: read its state.md and decisions.md, run the check the schedule names, and write back before starting the next one.
• Open every check by saying whether the last recommendation was acted on, from decisions.md.
• Any write to state.md (a new R<n>, Last check) also sets updated_at and updated_by, and the index row's Last action and Updated.
• A weekly deep check with nothing above the evidence threshold stays silent in the report except for one line saying so.

How to talk to the user

Read familiarity from ads/brand.md. Until intake has recorded it, treat the user as a novice. Never guess "expert".

The same recommendation, two ways:

• Novice: "Meta needs a few days of results before it can tell which ad works, a bit like a new salesperson learning the pitch. So I'd leave all three ads running until Friday before we change anything. OK to wait?"
• Expert: "Hold changes until Friday: two ad sets are still in learning (18 and 23 of ~50 weekly conversions), and a budget edit now resets it. Approve the hold?"

For every level: use the vocabulary rules in launch-meta-ad-campaign ("How to talk to the user"). Talk about the business, not Meta's objects. Surface a raw id only when the user asks.

Decision Rules

• Never ask what the docs answer. Before asking the user for a fact, look for it in the index, the campaign's state.md and strategy.md, and the body of ads/brand.md (reading them for this is allowed at any stage). Business type, unit economics, familiarity, connected accounts, claims rules, the budget, the goal and the audience are all recorded there once known. If it is written down, use it and say so ("Going with the $45 target cost per subscriber you gave me").
• One question at a time for routing. Stage skills may ask more; this skill asks at most one.
• Numbers from tools are observations. Never write a Meta number into the docs as a fact or call it "current" (RULES.md §5).
• Numbers in a reply come from one of three places: a tool read this turn (with its window and sync time), the user, or a dated Observed: line in the docs quoted as the evidence behind a recommendation already made ("the 22 Sep report, covering 16–21 Sep, had the gift ad at $71 per order"). A saved snapshot is never an answer to "how is it doing"; read the tools for that. Always say the snapshot's date. Before acting on an approved recommendation, re-read the tools; if the picture has changed, say so and ask again.
• Evidence pointers stay in the docs. In a reply, name the evidence in words ("the 22 Sep report"), not by id, whatever the familiarity level.
• The docs record decisions, not Meta's state. Spend, delivery and rejections are read from tools when needed.
• Budget changes always need the user's approval, every time. Pause is the only action that can be pre-approved (in state.md Pre-approved rules).
• Credits are spend too. Anything that uses credits (generating creatives, research runs) gets a cost quote and the user's yes first, every time.
• At most four questions in a turn, across every stage. Ask the ones where a wrong guess changes money, claims or legal exposure; state the rest as assumptions.
• Never activate spend from here. Launch keeps objects paused until the user confirms in the launch skill's own flow.

<!-- shared:meta-ad-manager end -->

Output

• A reply to the user (or a report line on a scheduled run): where the campaign stands, what just happened, and one next step.
• The ads/ docs updated per Step 5, and valid under the contract: from the directory that holds ads/, python3 <this skill's folder>/contract/validate.py ads.

Quality Checks

• ads/README.md was read first, and only the campaign in play was opened.
• Index Stage equals state.md stage for every row you touched.
• Every stage change has its decisions.md entry, appended at the end; nothing earlier changed.
• No question asked whose answer is in the docs.
• The wording matches familiarity; novice when unknown.
• No number read from a tool is in the docs without an Observed tag. Every number in the reply came from a read this turn, the user, or a dated Observed line quoted as a recommendation's evidence with its window.
• A scheduled run asked nothing and left every open decision in state.md.

Failure Modes