# The teardown framework

What `ad_intel.py` asks of the model, and the rules it holds the answer to. The prompt
below is read from this file at run time (between the `prompt:start` / `prompt:end`
markers), so this document and the runner cannot disagree.

## Where it comes from

The analysis method is ported, in our own words, from three MIT-licensed prose skills
that carry good frameworks over paid data access we do not use:

- ScrapeCreators, `ad-library-teardown` and `transcript-intelligence`
  (https://github.com/ScrapeCreators/social-media-research-skills, MIT) — cluster by
  pain point / persona / offer / proof / objection / urgency; a verbatim hooks swipe
  file; segment a spoken ad into hook → setup → claim → evidence → payoff → CTA;
  "active is not winning, repetition is the signal"; never invent spend or performance.
- davila7, `competitive-ads-extractor` (https://github.com/davila7/claude-code-templates,
  MIT) — the problems an advertiser keeps highlighting, the creative patterns that
  repeat, the copy that recurs.
- AgriciDaniel, `ads-competitor` (https://github.com/AgriciDaniel/claude-ads, MIT) —
  separate what is observed from what is inferred; record the capture date and source.

The data comes from our own browser on the public Meta Ad Library page (`adlib_fetch.py`)
or from a single public video URL. No third-party API is involved.

## The rules the runner enforces

1. **Active ≠ winning.** An ad that is running is evidence that someone keeps paying for
   it, nothing more. The page shows no spend, no CTR, no conversions; none is invented.
2. **Repetition is the signal.** "N ads use this creative" and a start date months back
   are the two facts the page gives; the teardown ranks by them.
3. **Verbatim or nothing.** The hook is the first spoken or shown words, quoted from the
   transcript, not paraphrased. Whisper is primed with the card's own text so brand and
   product words survive.
4. **Angles carry a category** from the ugc strategy vocabulary —
   `problem | mechanism | proof | offer | urgency | trust` — so a teardown drops straight
   into `skills/ugc`'s belief journey. An angle whose category is not one of those is
   dropped with a warning, never quietly relabelled.
5. **The UGC script is ours, not theirs.** It answers the same belief for the operator's
   brand in our voice; it never reuses the competitor's lines.
6. **Observed vs inferred.** `claims`, `offer`, `cta`, `proof` are what the ad says;
   `angles`, `objections`, `visual_pattern` are readings and are labelled as such on the
   page.

## The prompt

<!-- prompt:start -->
You are tearing down ONE paid social video ad for a marketing team that will write its
own ads afterwards. You receive the ad video (with sound), a word-level transcript of
its audio, and the text the advertiser put beside the video (page name, primary text,
headline, description, call to action, landing domain).

Answer with ONE JSON object and nothing else, with exactly these keys:

- "summary": two sentences — what the ad shows and what it is selling.
- "hook": the first spoken or on-screen words, QUOTED VERBATIM from the transcript or
  the frame (the first ~3 seconds). Never paraphrase.
- "structure": an array of {"segment", "start", "end", "note"} covering the whole ad in
  order, with segment one of "hook", "setup", "claim", "evidence", "payoff", "cta",
  "other"; start/end in seconds from the transcript timing.
- "claims": the concrete claims the ad makes, as short verbatim or near-verbatim strings.
- "offer": what is being offered and on what terms (price, free, trial, discount), or
  "none stated".
- "cta": the call to action as spoken or shown, or "none".
- "proof": social proof, numbers, demonstrations, testimonials the ad shows — observed
  only.
- "objections": the doubts the ad is pre-empting, as short strings — a reading, not an
  observation.
- "angles": an array of {"angle", "category"} — each positioning angle the ad leans on,
  where "category" is EXACTLY one of "problem", "mechanism", "proof", "offer",
  "urgency", "trust". Two to five entries.
- "visual_pattern": one sentence on the creative format (talking head, screen capture,
  before/after, product demo, text-on-screen, stock b-roll…) and pacing.
- "ugc_script": a 30–45 second spoken script FOR THE OPERATOR'S BRAND (named in the
  context, or "our product" if none) that answers the strongest angle in our own words.
  Do not reuse the competitor's sentences.

Rules: quote, do not embellish; if the audio has no speech say so in "hook" ("(no
speech; on-screen: …)"); do not invent spend, results, or targeting; keep every string
in the language of the ad.
<!-- prompt:end -->

## The set-level synthesis

With two or more ads for one brand, a second, text-only call reads every per-ad answer
and returns `{"positioning", "appearsToBeTesting": [...], "testsForUs": [...]}` — what
the advertiser seems to be A/B testing (same page, many versions, differing hooks) and
which of their angles our brand should test first, each tied to the ads that carry it.
The deterministic parts (angle clusters, the hooks swipe file, longest-running first)
are computed in code, not asked of the model.