Recharm

View saved version →

---
name: "aspire-tone-brief"
description: >
  Build a Recharm footage brief for an ad anchored in an optimistic purchasing emotion — show the prospect already thriving, not suffering from a problem. Use whenever a user provides a creative brief, concept, or ad idea and wants to frame it around a positive mindstate such as achievement, belonging, empowerment, autonomy, competence, engagement, esteem, nurturance, or security. Searches the Recharm clip library and produces a shareable shot-by-shot brief with clip picks. Trigger this skill whenever the user mentions "optimistic", "positive emotion", "aspirational", "feel-good ad", "celebrate the win", "prospect mindstate", or provides a brief with an uplifting, forward-looking angle — even if they don't name the mindstate explicitly. Also use this when the user asks for an ad that leads with the prospect's joy, confidence, freedom, connection, or sense of accomplishment rather than pain or fear.
---

# Aspire Tone Brief

You orchestrate a multi-step search loop against the user's Recharm clip library to turn a creative brief into a shot-by-shot brief anchored in a specific **optimistic purchasing emotion** (mindstate). The ad speaks _to_ the prospect while they are in that positive mindstate — it mirrors their aspiration, not their problem.

The Recharm MCP server (`recharm`) is available in this plugin. Key behavioral notes:

- Call `list_labels` once at the start — keep the result for the entire workflow; do not call it again per scene.
- You do NOT build HTML. You pick clips and hand `save_brief` a slim structured package; the server derives every clip's URLs, name, duration, and aspect ratio from its `clipSymbol` and renders the HTML.
- Call `save_brief` exactly once, after clip picks are final. Each call mints a new URL.
- Do not paginate `search_clips_visually` — use the first page only.
- Only use label values returned by `list_labels` — do not invent or guess label strings.

**Always refer to a clip in user-facing output as its `clipName` — `<clipSymbol> - <sceneType>`** (e.g. "AB - Product Reveal"). If `sceneType` is null, fall back to just the `clipSymbol`.

This skill processes one video at a time. If the brief calls for multiple videos, ask the user to pick one or confirm sequential processing.

Follow the steps below in order.

---

## The Nine Optimistic Mindstates

Each mindstate represents the positive emotional lens through which the prospect is viewing their world when they encounter the ad. The ad should _confirm and celebrate_ that feeling — not introduce doubt or fear.

| Mindstate                  | Core desire                                  | What the ad celebrates                            |
| -------------------------- | -------------------------------------------- | ------------------------------------------------- |
| **Optimistic Achievement** | Success, accomplishing goals                 | The win, the milestone, the earned result         |
| **Optimistic Autonomy**    | Freedom, self-expression, personal choice    | Being the author of one's own story               |
| **Optimistic Belonging**   | Connection, shared experiences, community    | Togetherness, tribe, being part of something      |
| **Optimistic Competence**  | Improvement, growth, doing one's best        | Getting better, leveling up, mastering something  |
| **Optimistic Engagement**  | Pleasure, excitement, full immersion in life | Joy, vitality, savoring the moment                |
| **Optimistic Empowerment** | Handling challenges, feeling capable         | Strength, readiness, rising to occasions          |
| **Optimistic Esteem**      | Recognition, appreciation, self-confidence   | Being seen, valued, proud of who you are          |
| **Optimistic Nurturance**  | Compassion, feeling loved, caring for others | Warmth, being cherished, giving or receiving care |
| **Optimistic Security**    | Safety, protection, peace of mind            | Confidence in the future, freedom from worry      |

---

## Step 1 — Identify the target mindstate(s)

**From the brief:** Read it for emotional cues — words like "earned it", "finally free", "part of something", "getting stronger", "peace of mind", etc. Map these to one or two mindstates from the table above.

**Ask for confirmation:** Present your read to the user:

> "I'm reading this as an **Optimistic [X]** ad — the prospect is feeling [brief description of what they're experiencing]. Does that resonate, or would you like to shift the emotional angle?"

If the brief is silent on emotion, ask the user to pick one. Do not proceed without a confirmed mindstate — it shapes every scene description.

**One primary mindstate:** Use at most two mindstates per brief. If two are chosen, designate one as primary (drives scene structure) and one as secondary (flavors individual scenes).

---

## Step 2 — Confirm the brand and content constraints

**Brand:** If the user already named a brand slug (e.g. `magic_spoon`, `hike_footwear`), use it. Otherwise call `list_brands` and ask the user to pick. If a user-named brand doesn't appear in `list_brands`, don't give up — call `list_labels` with that slug directly. Many brands work even when absent from the brands listing.

**ActorType preference:** By default, apply **both Actor B-roll and No Actor** labels to every search query — this gives the broadest b-roll pool while excluding talking heads, which tend to feel too direct for optimistic emotion-led ads. Only deviate if the brief explicitly requests talking heads or UGC-style on-camera content, in which case confirm with the user before removing the filter.

---

## Step 3 — Fetch available labels

Call `list_labels(brandName)` and keep the result for the rest of the workflow. Note these special-case categories if present:

- **Scene Type**: each clip belongs to exactly one Scene Type (`Hook`, `CTA`, `Product Benefits`, `Product Shot`, `Bowl Shot`, `Box Shot`, `Pouring Cereal`, etc.)
- **Actor Type**: whether a person appears and whether they are speaking
- **Product**: specific flavors or SKUs

---

## Step 4 — Section the brief through the mindstate lens

Read the brief and break it into **ordered scenes**. Each scene should be approximately 2–5 seconds and correspond to a single Recharm clip. Cap the total at **18 scenes**.

**Mindstate-driven scene architecture:** Structure scenes to take the viewer on an emotional arc _within_ the chosen mindstate — starting from a moment that resonates with their current positive feeling, deepening it, and closing with the product as a natural extension of that feeling.

Typical arc shapes by mindstate:

- **Achievement / Competence / Empowerment:** Open on effort or momentum → show the peak moment / the win → product as the trusted companion that got them there.
- **Belonging / Nurturance:** Open on connection or warmth → deepen the shared moment → product as part of the ritual or gift.
- **Autonomy / Engagement:** Open on freedom or pleasure → show full immersion in the experience → product as the enabler.
- **Esteem:** Open on a confident, proud moment → amplify with recognition → product as a natural choice for someone like them.
- **Security:** Open on calm confidence → show life running smoothly → product as the quiet guardian of that peace.

For each scene capture:

- A short heading (e.g. "Hook — athlete cresting a hill at sunrise")
- 1–2 sentences describing what should appear on screen
- The **emotional beat** — what the viewer is feeling in this moment and how it ties to the mindstate
- The narrative role (hook / build / peak / product reveal / CTA)

**Show the proposed scene breakdown to the user and wait for confirmation before searching.**

---

## Step 5 — Build search queries

For each scene, generate **2–4 search queries**. Each query has:

- A short visual phrase (under ~8 words) describing what is literally on screen. Be concrete and visual — "woman crossing finish line arms raised" beats "achievement". Vary phrases to cover different subjects, framings, and environments.
- An optional `filters` object.

### Filter rules

**Default to lean filtering.** The text query does most of the heavy lifting. As a default, add at most **1 label category** per query (beyond the ActorType baseline). Only combine two categories when the brief has a genuinely hard constraint requiring both.

**ActorType filter:** Apply Actor B-roll and No Actor labels to every query (the default). This is a baseline constraint, not counted toward the "1 label category" default.

**Scene Type filter:** Use the Scene Type that best matches the scene's narrative role: `Hook` / `Visual Hook` for openers; product-specific types for food/product B-roll; `CTA` for closers.

**Product filter:** If the brief names a specific flavor or SKU, apply the matching `Product` label on queries where the product is the hero.

---

## Step 6 — Search, section by section

**Run all first-round queries in parallel** — fire all 2–4 queries per scene simultaneously in the same tool call batch.

For each scene:

1. Call `search_clips_visually` once per query phrase, passing `brandName`, `query`, and any `filters`.
2. Select the **1–2 top results per query** by lowest `cosineDistance`.
3. Aim for **3–6 clips per scene** total. Deduplicate by `clipSymbol`.
4. Use **at most one clip per `rawVideoPublicId`** within a scene — clips sharing a `rawVideoPublicId` are different moments of the same source video. Keep the best.
5. Track, per picked clip, the **query phrase** and **filters** used — both go into the brief package.
6. If all results for a scene have weak scores, leave that scene's clip list empty (renders as "custom shoot needed") and note it in the summary.

**Mindstate alignment check:** As you review results, notice whether clips feel emotionally congruent with the mindstate. A clip can have a great cosineDistance but feel flat or neutral — for this brief type, warmth, energy, and emotional charge matter. If two clips are close in score, pick the one that better embodies the emotional beat.

---

## Step 7 — Assemble the brief package

Do **not** write HTML. Build a slim structured package:

- `title`: e.g. `"Magic Spoon · Optimistic Achievement · Runner's Morning"`
- `scenes`: ordered scenes. Each scene:
  - `name`: the scene heading
  - `description`: the 1–2 sentence on-screen description **plus** a parenthetical emotional beat note, e.g. `"Close-up of hands lacing up trail shoes before a run. (Beat: quiet confidence — she's done this a hundred times and knows what's ahead.)"`
  - `clips`: picked clips. Each clip:
    - `clipSymbol`
    - `searchString`
    - `filters`
  - Empty `clips` array for custom shoot scenes.

---

## Step 8 — Save and share the brief

Call `save_brief` exactly once with the **v2** payload:

```
save_brief(brandName, {
  version: "v2",
  title: "<brief title>",
  scenes: [
    {
      name: "<scene heading>",
      description: "<on-screen description + emotional beat note>",
      clips: [
        { clipSymbol: "<symbol>", searchString: "<query phrase>", filters: { <category>: ["<label>"] } }
      ]
    }
  ]
})
```

Surface the returned `url` as the shareable link. Then give the user a short **overall summary**:

- Which mindstate(s) the brief targets and how the arc lands
- Scenes needing custom footage
- Any emotional-alignment gaps (scenes where the best clips feel tonally off)
- Cross-cutting observations about the library's depth for this mindstate

---

## What not to do

- Don't skip the mindstate confirmation step — it's the whole point of this brief type.
- Don't describe scenes in abstract terms — visual specificity drives better search results.
- Don't use label values not returned by `list_labels`.
- Don't over-filter — default to 1 label category per query (beyond ActorType).
- Don't pad picks with weak matches without noting it.
- Don't invent `clipSymbol`s — only use ones returned by `search_clips_visually`.
- Don't refer to a clip by `clipSymbol` alone in user-facing output — always use `clipName`.
- Don't build HTML or construct clip URLs — hand `save_brief` the v2 package.
- Don't call `save_brief` more than once or before clip picks are final.
- Don't give up if a user-named brand doesn't appear in `list_brands` — try `list_labels` directly.

View saved version →

---
name: "authority-ad-brief"
description: >
  Build a Recharm footage brief for an AUTHORITY ad — borrow the credibility of experts, credentials, science, or institutions so the viewer defers to trusted judgment instead of evaluating from scratch. Use whenever a user provides a brief, concept, or ad idea framed around expert endorsement, 'doctor recommended', 'formulated by', scientific backing, certifications, pro-grade positioning, or credential-led trust. Searches the user's Recharm clip library and produces a shareable shot-by-shot brief with clip picks. Trigger on "authority", "expert ad", "doctor recommended", "dermatologist", "nutritionist", "scientifically proven", "lab tested", "what the pros use", or any creative fronted by one qualified voice rather than a crowd. Distinct from social proof (many ordinary voices) — authority is one credible expert voice.
---

# Authority Ad Brief

You build a Recharm footage brief for a **authority** ad — one that borrows the credibility of experts, credentials, science, or institutions so the viewer defers to trusted judgment instead of evaluating from scratch.

The psychological engine: people defer to legitimate expertise. When a credible authority — a doctor, coach, scientist, certification body — vouches for the product, evaluation shortcuts to trust. This is distinct from social proof (many ordinary voices — this is *one qualified voice*), from liking (warmth), and from herd psychology (crowd feeling). The ad must establish the credential before spending it.

The Recharm MCP server (`recharm`) is available in this plugin. Key behavioral notes:

- Call `list_labels` once at the start — keep the result for the entire workflow; do not call it again per scene.
- Search hits from `search_clips_visually` already include `posterUrl` and `previewUrl` — use them directly. Only call `get_clip_poster_image` as a fallback if a hit is missing `posterUrl`.
- The template builds "View clip" and "Find similar" links itself from `clipSymbol`, `brand`, and `searchString` — you don't construct any Recharm app URLs.
- Do not paginate `search_clips_visually` — use the first page only.
- Only use label values returned by `list_labels` — do not invent or guess label strings.
- Do **NOT** call `save_brief`. Instead, render the brief using `templates/brief.html` and upload via `save_html_file`.

**Always refer to a clip in user-facing output as its `clipName` — `<clipSymbol> - <sceneType>`** (e.g. "AB - Product Reveal"). If `sceneType` is null, fall back to just the `clipSymbol`.

Follow the steps below in order.

---

## Step 1 — Confirm the brand, hook, and content constraints

**Brand:** If the user already named a brand slug (e.g. `magic_spoon`, `hike_footwear`), use it. Otherwise call `list_brands` and ask the user to pick. If a user-named brand doesn't appear in `list_brands`, don't give up — call `list_labels` with that slug directly.

**Hook selection:** Choose the best-fitting authority hook pattern for the brief. If the user provided a specific hook line, use it and map it to the closest pattern. Make your pick, write a one-sentence rationale, and note why you're rejecting the others — you'll need all of this for the final brief output.

**Authority hook patterns:**
- *Expert Confession* — "A [dermatologist] told me to stop doing this immediately."
- *Credential Open* — "I've spent 15 years as a [profession]. This is what I actually use."
- *Science Lead* — "The study that changed how I think about [category]."
- *Formulated-By* — "Designed by [experts] who got tired of what's on shelves."
- *Insider Warning* — "As a [profession], here's what I'd never buy."
- *Award Stack* — "Backed by [certification], tested by [lab], used by [pros]."
- *Myth Bust* — "A [expert] debunks the biggest [category] myth."
- *Pro Standard* — "What [pros/athletes] use when nobody is sponsoring them."
- *Checklist Authority* — "The three things a [expert] checks before buying any [category]."
- *White Coat Reveal* — "Turns out your [doctor] was right about this one."

**ActorType preference:** Authority ads need footage that reads competent and credible — precision, professional settings, mastery. Confirm with the user:
- **No Actor** — purely product/environment footage
- **Actor B-roll** — hands, partial body, people in motion (recommended)
- **Both** (No Actor + Actor B-roll) — good default
- **No filter** — include all footage

**Brand-fit rationale:** While confirming, form a view on *why authority will work for this specific brand* — what real credentials, experts, studies, or certifications does it have to spend, and will its buyers recognize that authority as legitimate? You'll write this into the brief's `why.brandFit` field in Step 6 so anyone opening the brief understands the strategy, not just the shot list.

---

## Step 2 — Fetch available labels

Call `list_labels(brandName)` and keep the result for the rest of the workflow. Note:
- **Scene Type**: `Hook`, `Visual Hook`, `CTA`, `Product Benefits`, `Product Shot`, `Lifestyle`, `Bowl Shot`, `Box Shot`, etc.
- **Actor Type**: whether a person appears and whether they are speaking.
- **Product**: maps to specific flavors or SKUs.

---

## Step 3 — Section the brief using the authority narrative arc

Break the brief into **10–14 scenes** using this arc:

| Arc segment | Typical scenes | Purpose |
|---|---|---|
| **Hook** | 1–2 | Lead with the authority signal — credential, uniform, lab, professional setting. The viewer registers "qualified voice" instantly. |
| **Credential Stack** | 2–3 | Establish why this voice is trusted — expertise in action, professional environments, mastery on display. |
| **Expert Insight** | 1–2 | The authority's key insight or standard — what most products in the category get wrong. Tension before the answer. |
| **Product Reveal** | 1–2 | The product that meets the expert's standard — the one that passes the test. |
| **Benefit Payoff** | 2–3 | Evidence the expert would cite — ingredients, mechanisms, measurable results. |
| **Endorsement Seal** | 1 | The trust moment — confident daily use, the professional's own choice. |
| **CTA** | 1 | "Expert-approved" / "Try what the pros use." |

For each scene capture:
- `name`: short heading (e.g. "Hook — nutrition label inspected in bright kitchen")
- `description`: 1–2 sentences describing what appears on screen
- `arcSegment`: one of the 7 arc segment names above (must match exactly — the HTML uses these for color-coding)

**If the user supplied an explicit scene breakdown, use it. Otherwise show the proposed breakdown and wait for confirmation.**

---

## Step 4 — Build search queries

For each scene, generate **3–5 search queries** — short visual phrases (under ~8 words) describing what is literally on screen, not abstract concepts. Vary phrases to cover different subjects, framings, and environments. You need enough query diversity to surface **4 strong, visually distinct clips per scene** — a single query rarely gets you there.

### Filter rules
- Apply ActorType labels to every query (baseline, not counted toward the category limit).
- Add at most **1 additional label category** per query (Scene Type or Product).
- Use Scene Type matching the arc segment: Hook/Visual Hook for the hook; Lifestyle/Product Benefits for the middle segments; Product Shot for the reveal; CTA for the close.
- Apply Product label only for scenes where the specific SKU is the hero.

---

## Step 5 — Search and collect clip media

**Run all first-round queries in parallel** (all 3–5 queries per scene in one batch). Then fill gaps with follow-up queries only where needed.

For each scene:
1. Call `search_clips_visually` with `brandName`, `query`, and any `filters`.
2. Pool the results from all of the scene's queries and pick the **4 best clips** — rank primarily by lowest `cosineDistance`, but prefer visual variety (different framings, subjects, environments) over four near-identical picks.
3. Deduplicate by `clipSymbol`. Use **at most one clip per `rawVideoPublicId`** — clips sharing a source video look near-identical; keep the best (lowest cosineDistance).
4. If a scene has fewer than 4 strong matches after the first round, run 1–2 follow-up queries with different phrasings before settling for fewer. A scene may ship with 2–3 clips if the library is genuinely thin — never pad with weak matches (cosineDistance well into the "weak" range) just to hit 4.
5. Take `posterUrl` and `previewUrl` directly from the search hit. If a hit is missing `previewUrl` and has a `rawVideoPublicId`, derive it: `https://res.cloudinary.com/recharm/video/upload/so_0,eo_4,q_auto,f_auto/{rawVideoPublicId}.mp4`.
6. Track per clip: `clipSymbol`, `clipName`, `posterUrl`, `previewUrl`, `cosineDistance`, `searchString`, `filters`. `searchString` must be the **exact query string** used in the `search_clips_visually` call that surfaced the clip — the template uses it to build the "Find similar" link, which reopens the full visual-search result set (including the clips you considered but rejected). The template also builds each "View clip" link from `clipSymbol`, so `clipSymbol` must be exactly as returned.
7. Scenes with no strong matches → `clips: []` (renders as "custom shoot needed" gap in the HTML).

**Arc-specific search guidance:**
- **Hook:** Professional settings — labs, kitchens-as-workspaces, gyms with coaching energy, clean clinical environments.
- **Credential Stack:** Competence footage — precise measuring, careful preparation, athletic performance, focused work.
- **Expert Insight:** Ingredient close-ups, label inspection, side-by-side comparison gestures, analytical beats.
- **Product Reveal / Benefit / CTA:** Product Shot, Benefits, CTA Scene Types; favor clean, precise, "specification-grade" framing.

---

## Step 6 — Assemble the JSON data payload

Build this object — the HTML template renders everything from it:

```json
{
  "title": "<e.g. 'What Nutritionists Actually Eat · Magic Spoon · Frosted'>",
  "brand": "<brandName slug>",
  "generatedAt": "<YYYY-MM-DD>",
  "filterChips": [
    { "category": "Actor Type", "value": "Actor B-Roll" },
    { "category": "Actor Type", "value": "No Actor" },
    { "category": "Product", "value": "Frosted" },
    { "category": "Scenes", "value": "12" }
  ],
  "why": {
    "explainer": "<2–3 sentences: what a authority ad is and the mechanism that makes it convert — a qualified, credible voice lets buyers shortcut evaluation and defer to trusted judgment. Written for someone who has never heard the term.>",
    "brandFit": "<2–3 sentences: why this mechanism fits THIS brand specifically — its category, how its buyers decide, and the context that makes the authority angle credible.>"
  },
  "hook": {
    "pattern": "<Pattern name, e.g. 'Credential Open'>",
    "line": "<The actual hook line, e.g. 'I've spent 15 years as a nutritionist. This is what I actually eat.'>",
    "rationale": "<1–2 sentences: why this hook fits this brand and audience>"
  },
  "rejectedHooks": [
    {
      "pattern": "<Pattern name>",
      "line": "<What the hook line would have been>",
      "reason": "<1 sentence — specific reason this pattern is a weaker fit here>"
    }
  ],
  "actorType": "<e.g. 'Both (Actor B-Roll + No Actor)'>",
  "scenes": [
    {
      "name": "<Scene heading>",
      "arcSegment": "<Exactly one of: Hook | Credential Stack | Expert Insight | Product Reveal | Benefit Payoff | Endorsement Seal | CTA>",
      "description": "<1–2 sentences of on-screen description>",
      "clips": [
        {
          "clipSymbol": "<symbol>",
          "clipName": "<clipName from search result>",
          "posterUrl": "<posterUrl from the search hit>",
          "previewUrl": "<previewUrl from the search hit, or derived from rawVideoPublicId, or null>",
          "cosineDistance": 0.142,
          "searchString": "<exact query phrase used to find this clip>",
          "filters": { "<category>": ["<label>"] }
        }
      ]
    }
  ]
}
```

Notes:
- `filterChips` is what renders under the title — one chip per applied footage filter. Include every ActorType label applied, any Product/Scene Type filters used broadly, and a `Scenes` count chip. Keep values short (chip-sized) — this replaces the old prose subtitle.
- `why.explainer` and `why.brandFit` render as a prominent "Why this approach" panel — write them for a reader who has never heard of the authority lever and needs to be convinced it fits their brand. Target **4 clip picks per scene** in `clips`.
- Include **at least 5 rejected hooks** in `rejectedHooks` with specific, brand-aware reasons so the user understands the creative logic behind the chosen pattern.

---

## Step 7 — Render and save the brief

1. **Read** `templates/brief.html` (in this skill's directory).
2. **Replace** the exact string `__BRIEF_DATA_JSON__` with the JSON payload (serialized as a single string — no pretty-printing needed, just ensure it is valid JSON). After serializing, replace every `</` with `<\/` in the JSON string — the payload lives inside an inline `<script>` tag, and an unescaped `</` in any text field would terminate the script and break the whole page.
3. **Call the Recharm MCP `save_html_file` tool** with:
   - `brandName`: the brand slug used throughout this workflow
   - `html`: the fully rendered HTML string (max 20 MB)

   This uploads the HTML to Recharm's public-share storage and returns a shareable `url`.
4. **Surface the `url`** to the user.
5. Give a short **summary**: custom-shoot gaps, scenes that shipped with fewer than 4 clips, arc segments with thin library coverage, any weak-match clips flagged.

---

## What not to do

- Don't confuse authority with social proof — proof is many ordinary voices; authority is one qualified voice. If the angle is review counts and testimonials, use social-proof-ad-brief.
- Don't use authority claims the brand can't substantiate — real credentials, real studies, real certifications only. Invented expertise is a legal risk; flag anything that seems fabricated.
- Don't reveal the product before the Expert Insight — protect the tension arc.
- Don't settle for 1 clip per scene — the brief is a menu, not a lock; editors need 4 options per scene to cut alternates.
- Don't pad to 4 clips with weak matches — 2–3 strong picks beat 4 with a dud.
- Don't drop `posterUrl`/`previewUrl` from search hits — the template needs them for thumbnails and hover previews.
- Don't add download links — raw downloadable video URLs aren't available; "View clip" and "Find similar" open in the Recharm app.
- Don't call `save_brief` — use the Recharm MCP `save_html_file` tool with `brandName` + `html`.
- Don't use label values not returned by `list_labels`.
- Don't over-filter — default to 1 label category per query beyond ActorType.
- Don't invent `clipSymbol`s — only use ones returned by `search_clips_visually`.
- Don't refer to a clip by `clipSymbol` alone — always use `clipName` in user-facing output.
- Don't paraphrase `searchString` — it must be the exact query used, or the visual-search results link in the brief won't reproduce the search.
- Don't call `save_html_file` more than once per brief — each call mints a new URL.
- Don't give up if a brand doesn't appear in `list_brands` — try `list_labels` directly.

Referenced files: 1 — file references are metadata, not package contents.

View saved version →

---
name: "brief-creator"
description: Turn an end-to-end video creative brief into a sectioned shot list, search the user's Recharm clip library for footage that fits each section using label-based filters, and produce a final creative brief with picks. Use whenever a user provides a brief/script/storyboard and asks for matching footage from Recharm.
---

# Find Video Footage for a Brief

You orchestrate a multi-step search loop against the user's Recharm clip library to turn a creative brief into a shot-by-shot brief with concrete clip picks. You use label-based filters to constrain searches — no visual review of clips is performed.

The Recharm MCP server (`recharm`) is available in this plugin. Key behavioral notes:

- Call `list_labels` once at the start — keep the result for the entire workflow; do not call it again per scene.
- You do NOT build HTML. You pick clips and hand `save_brief` a slim structured package; the server derives every clip's URLs, name, duration, and aspect ratio from its `clipSymbol` and renders the HTML.
- Call `save_brief` exactly once, after the clip picks are final. Each call mints a new URL.
- Do not paginate `search_clips_visually` — use the first page only.
- Only use label values returned by `list_labels` — do not invent or guess label strings.

Please check the actual MCP server data for up-to-date API info.

**Always refer to a clip in user-facing output as its `clipName` — `<clipSymbol> - <sceneType>`** (e.g. "AB - Product Reveal"). If `sceneType` is null, fall back to just the `clipSymbol`.

This skill processes one video at a time. If you detect that the provided brief calls for creating multiple videos, prompt the user up front whether to run the skill once per video (sequentially) or pick a single video to process — then follow the steps below for each chosen video.

Follow the steps below in order.

## Before you begin — capture the prompt

Note the user's verbatim opening message now — before any processing. By Step 7, `prompt` will include this plus any further input they gave during the workflow (see below).

**File attachments (PDF, Word doc, etc.):** if the user attached a file, read its full content and treat it as the brief. For `prompt`, start with the filename, then a newline, then the full extracted text of the file — not a summary. If the user also typed an accompanying message (e.g. "make this into a brief"), prepend that message followed by a newline before the filename and content.

**Subsequent user input:** as the workflow progresses, append any further instructions, corrections, clarifications, or interruptions the user provides — verbatim. This includes answers to questions you asked, changes of direction, feedback on scene breakdowns, or anything else they typed. The goal is that a viewer of the brief can reconstruct the full intent from `prompt` alone.

## Step 1 — Confirm the brand

- If the user already named a brand slug (e.g. `lululemon`, `hike_footwear`), use it.
- Otherwise call `list_brands` and ask the user to pick.
- Do not guess the brand if there is any ambiguity.

## Step 2 — Fetch available labels

Call `list_labels(brandName)` and keep the result for the rest of the workflow. You will use these categories and labels to build search filters. Do not invent or use label values that were not returned by this call.

Note the following special-case categories if present:

- **SceneType**: each clip belongs to exactly one SceneType. Useful values include `Hook`, `CTA`, `Product Benefit`, `Demo`, and `Product Shot`.
- **ActorType**: indicates whether a person appears and whether they are speaking.

## Step 3 — Section the brief

Read the brief and break it into ordered scenes. Each scene should be approximately 2–5 seconds and correspond to a single Recharm clip. Cap the total at **18 scenes**.

For each scene capture:

- A short heading (e.g. "Hook — runner laces up at dawn")
- 1–2 sentences describing what should appear on screen
- The narrative role (hook / problem / product reveal / benefit / proof / CTA / etc.) when the brief implies one

If the user supplied an explicit scene breakdown, use it and skip to Step 4. Otherwise, **show the proposed scene breakdown to the user and wait for confirmation before proceeding.**

If a transcript (also called voiceover or VO) is provided, use it to inform what each scene should show — but section the brief independently of transcript timing.

## Step 4 — Build search queries

For each scene, generate **2-4 search queries**. Each query has:

- A short visual phrase (under ~8 words) describing what is literally on screen — not abstract concepts. "woman tying running shoes on porch" beats "morning motivation". Vary phrases across queries to cover different subjects, framings, and environments.
- An optional `filters` object with 0–3 categories and 1-2 labels from the `list_labels` response.

### Filter rules

**SceneType filter:** use the SceneType that best matches the scene's narrative role when a relevant SceneType exists in the label list.

**ActorType filter (transcript constraint):** if a transcript (or voiceover/VO) was provided AND `ActorType` is present in the `list_labels` response, add `ActorType: ["Actor B-roll", "No Actor"]` as a hard filter on every query. If `ActorType` is absent from the label list, omit this filter entirely.

**Product filter:** if a specific product was named in the input:

1. Look for a product-related label category in the `list_labels` response.
2. If found, match the product name to the closest available label. If you are unsure which label is the right match, ask the user to pick before searching.
3. If no product label category exists, include the product name in the text query phrase for scenes where it is relevant (product shots, demos, CTAs) — not mechanically on every scene.

**General filter guidance:** supply multiple labels within a category to broaden results (OR logic within a category). Only combine multiple categories when both constraints are genuinely required (AND logic across categories) — over-filtering will return too few results.

## Step 5 — Search, section by section

Each `search_clips_visually` hit is slim: `clipSymbol`, `clipName`, `rawVideoPublicId`, `sceneType`, `cosineDistance` (lower is closer), `durationMs`, and `categoriesAndLabels` (top hits). No media URLs are returned — pick clips by `clipSymbol` and the server derives the rest at render time.

For each scene:

1. Call `search_clips_visually` once per query phrase, passing `brandName`, `query`, and any `filters`. Do not paginate — use only the first page of results.
2. Select the **1–2 top results per query** by lowest `cosineDistance`. Do not fetch or examine poster images or sprite images.
3. Aim for **3–6 clips per scene** total (across all queries). Deduplicate by `clipSymbol` — if the same clip appears in multiple query results, count it once and attribute it to the query with the best cosineDistance.
4. Use **at most one clip per `rawVideoPublicId`** within a scene — clips sharing a `rawVideoPublicId` are different moments of the same source video and look near-identical. Keep the best (lowest cosineDistance) and drop the rest, so each scene's picks are visually varied.
5. Track, per picked clip, the **query phrase** and the **filters** used in the search that surfaced it — both go into the brief package in Step 6.
6. If all results for a scene have weak cosineDistance scores, leave that scene's clip list empty (Step 6) so it renders as a "custom shoot needed" gap, and note it in the overall summary to the user.

## Step 6 — Assemble the brief package

Do **not** write HTML. Build a slim structured package the server will render:

- `title`: a short brief title, e.g. `"5 Outdated Rules" · UGC Testimonial · Women 50+`.
- `prompt`: the user's original message, verbatim — the exact text captured before Step 1. Along with further input. Do not paraphrase.
- `scenes`: the ordered scenes from Step 3. Each scene is:
  - `name`: the scene heading.
  - `description`: the 1–2 sentence on-screen description from Step 3.
  - `clips`: the picked clips for the scene, in order. Each clip is:
    - `clipSymbol`: the `clipSymbol` from the `search_clips_visually` hit.
    - `searchString`: the query phrase that surfaced this clip (Step 4/5).
    - `filters`: the label filters used in that search, if any (the same `filters` object you passed to `search_clips_visually`).
  - For a scene that needs a custom shoot (no strong matches), use an **empty `clips` array** — it renders as a "custom shoot needed" gap.

You do not provide URLs, durations, dimensions, aspect ratios, or display names — the server derives all of those from each `clipSymbol`.

## Step 7 — Save and share the brief

Once the package is assembled, call `save_brief` exactly once with the **v2** payload:

```
save_brief(brandName, {
  version: "v2",
  title: "<brief title>",
  prompt: "<user prompt message(s) as mentioned in Step 1>",
  scenes: [
    {
      name: "<scene heading>",
      description: "<on-screen description>",
      clips: [
        { clipSymbol: "<symbol>", searchString: "<query phrase>", filters: { <category>: ["<label>"] } }
      ]
    }
    // ...a scene needing a custom shoot uses: { name, description, clips: [] }
  ]
})
```

The tool derives, renders, and uploads the HTML, returning `{ url, briefId, s3Key }` — surface the `url` to the user as the shareable link. After saving, give the user a short **overall summary**: scenes that need custom footage, cross-cutting observations, and obvious gaps in the brand's library. If the call fails, report the failure and show the structured package you assembled.

## What not to do

- Don't fetch or examine poster images or sprite images — clip selection is based on cosineDistance and text metadata only.
- Don't use label values that were not returned by `list_labels` — the API will reject them.
- Don't over-filter: combining many categories will produce too few results.
- Don't pad picks with weak matches without a warning note.
- Don't invent `clipSymbol`s — only use ones returned by `search_clips_visually`.
- Don't refer to a clip by `clipSymbol` alone in user-facing output — always use `clipName`.
- Don't ask the user to run searches themselves — you do it via the MCP.
- Don't build HTML or construct clip URLs yourself — hand `save_brief` the v2 structured package and let the server render.
- Don't call `save_brief` more than once per brief, and don't call it before the clip picks are final.

View saved version →

---
name: "commitment-consistency-ad-brief"
description: >
  Build a Recharm footage brief for a COMMITMENT & CONSISTENCY ad — open by surfacing an identity or goal the viewer has already claimed ('you said this was your year'), stack small yeses, then position the product as the consistent next step. Use whenever a user provides a brief, concept, or ad idea framed around keeping promises, staying on-streak, identity-based selling, micro-commitments, or New Year's-resolution energy. Searches the user's Recharm clip library and produces a shareable shot-by-shot brief with clip picks. Trigger on "commitment", "consistency", "identity ad", "keep your promise", "you said you would", "stay on track", "micro-yes", "if you're the kind of person who", or any creative where the lever is the viewer's own prior commitment. Also use for goal-callback or streak-keeper style ads.
---

# Commitment & Consistency Ad Brief

You build a Recharm footage brief for a **commitment & consistency** ad — one that opens by surfacing a commitment or identity the viewer already holds, stacks small agreements, then positions the product as the way to stay consistent with who they've said they are.

The psychological engine: people strive to act consistently with what they've already said and done. When an ad earns a small "yes" — an identity claim, a goal already declared, a value the viewer holds — the product becomes the way to honor that self-image. This is distinct from a problem-aware ad (pain-led) or a herd ad (crowd-led): the driver is *the viewer's own prior commitment*, and the tone is "stay true to yourself," never shame.

The Recharm MCP server (`recharm`) is available in this plugin. Key behavioral notes:

- Call `list_labels` once at the start — keep the result for the entire workflow; do not call it again per scene.
- Search hits from `search_clips_visually` already include `posterUrl` and `previewUrl` — use them directly. Only call `get_clip_poster_image` as a fallback if a hit is missing `posterUrl`.
- The template builds "View clip" and "Find similar" links itself from `clipSymbol`, `brand`, and `searchString` — you don't construct any Recharm app URLs.
- Do not paginate `search_clips_visually` — use the first page only.
- Only use label values returned by `list_labels` — do not invent or guess label strings.
- Do **NOT** call `save_brief`. Instead, render the brief using `templates/brief.html` and upload via `save_html_file`.

**Always refer to a clip in user-facing output as its `clipName` — `<clipSymbol> - <sceneType>`** (e.g. "AB - Product Reveal"). If `sceneType` is null, fall back to just the `clipSymbol`.

Follow the steps below in order.

---

## Step 1 — Confirm the brand, hook, and content constraints

**Brand:** If the user already named a brand slug (e.g. `magic_spoon`, `hike_footwear`), use it. Otherwise call `list_brands` and ask the user to pick. If a user-named brand doesn't appear in `list_brands`, don't give up — call `list_labels` with that slug directly.

**Hook selection:** Choose the best-fitting commitment & consistency hook pattern for the brief. If the user provided a specific hook line, use it and map it to the closest pattern. Make your pick, write a one-sentence rationale, and note why you're rejecting the others — you'll need all of this for the final brief output.

**Commitment & Consistency hook patterns:**
- *Identity Check* — "If you're the kind of person who [X], keep watching."
- *Goal Callback* — "Remember when you said this was the year you'd [X]?"
- *Micro-Yes* — "Agree that [obvious truth]? Then you already agree with what's next."
- *Streak Keeper* — "You didn't come this far to only come this far."
- *Values Mirror* — "You care about [value] — so why is your [category] working against it?"
- *Resolution Rescue* — "Your January goal called. It's not dead yet."
- *Public Promise* — "You told everyone you'd [X]. Here's the easy way to actually keep it."
- *Small-Step Ladder* — "Start with ten seconds a day. That's it. That's the whole ask."
- *Already-Doing-It* — "You're already [adjacent habit] — this just finishes the job."
- *Consistency Test* — "Would the [ideal-self] version of you skip this?"

**ActorType preference:** Commitment ads need footage of routine and follow-through — people mid-habit. Confirm with the user:
- **No Actor** — purely product/environment footage
- **Actor B-roll** — hands, partial body, people in motion (recommended)
- **Both** (No Actor + Actor B-roll) — good default
- **No filter** — include all footage

**Brand-fit rationale:** While confirming, form a view on *why commitment & consistency will work for this specific brand* — what commitment or identity do its buyers already hold (fitness goals, health resolutions, values) that the product can credibly serve as the next consistent step for? You'll write this into the brief's `why.brandFit` field in Step 6 so anyone opening the brief understands the strategy, not just the shot list.

---

## Step 2 — Fetch available labels

Call `list_labels(brandName)` and keep the result for the rest of the workflow. Note:
- **Scene Type**: `Hook`, `Visual Hook`, `CTA`, `Product Benefits`, `Product Shot`, `Lifestyle`, `Bowl Shot`, `Box Shot`, etc.
- **Actor Type**: whether a person appears and whether they are speaking.
- **Product**: maps to specific flavors or SKUs.

---

## Step 3 — Section the brief using the commitment & consistency narrative arc

Break the brief into **10–14 scenes** using this arc:

| Arc segment | Typical scenes | Purpose |
|---|---|---|
| **Hook** | 1–2 | Surface a commitment or identity the viewer already holds — earn the first small yes. |
| **Micro-Yes Ladder** | 2–3 | Stack small agreements: relatable moments that make the viewer nod along, each one a tiny commitment. |
| **Identity Mirror** | 1–2 | Show the viewer's ideal self in action — the person they've committed to being, just out of reach. |
| **Product Reveal** | 1–2 | The product lands as the tool that keeps the commitment — the bridge between claimed identity and daily behavior. |
| **Benefit Payoff** | 2–3 | Show how easy consistency becomes — results, effortless routine integration, visible progress. |
| **Commitment Lock** | 1 | Identity and product now aligned — the viewer's future self, on-streak and thriving. |
| **CTA** | 1 | "Keep your promise" / "Stay consistent" / "Finish what you started." |

For each scene capture:
- `name`: short heading (e.g. "Hook — lacing up running shoes at dawn")
- `description`: 1–2 sentences describing what appears on screen
- `arcSegment`: one of the 7 arc segment names above (must match exactly — the HTML uses these for color-coding)

**If the user supplied an explicit scene breakdown, use it. Otherwise show the proposed breakdown and wait for confirmation.**

---

## Step 4 — Build search queries

For each scene, generate **3–5 search queries** — short visual phrases (under ~8 words) describing what is literally on screen, not abstract concepts. Vary phrases to cover different subjects, framings, and environments. You need enough query diversity to surface **4 strong, visually distinct clips per scene** — a single query rarely gets you there.

### Filter rules
- Apply ActorType labels to every query (baseline, not counted toward the category limit).
- Add at most **1 additional label category** per query (Scene Type or Product).
- Use Scene Type matching the arc segment: Hook/Visual Hook for the hook; Lifestyle/Product Benefits for the middle segments; Product Shot for the reveal; CTA for the close.
- Apply Product label only for scenes where the specific SKU is the hero.

---

## Step 5 — Search and collect clip media

**Run all first-round queries in parallel** (all 3–5 queries per scene in one batch). Then fill gaps with follow-up queries only where needed.

For each scene:
1. Call `search_clips_visually` with `brandName`, `query`, and any `filters`.
2. Pool the results from all of the scene's queries and pick the **4 best clips** — rank primarily by lowest `cosineDistance`, but prefer visual variety (different framings, subjects, environments) over four near-identical picks.
3. Deduplicate by `clipSymbol`. Use **at most one clip per `rawVideoPublicId`** — clips sharing a source video look near-identical; keep the best (lowest cosineDistance).
4. If a scene has fewer than 4 strong matches after the first round, run 1–2 follow-up queries with different phrasings before settling for fewer. A scene may ship with 2–3 clips if the library is genuinely thin — never pad with weak matches (cosineDistance well into the "weak" range) just to hit 4.
5. Take `posterUrl` and `previewUrl` directly from the search hit. If a hit is missing `previewUrl` and has a `rawVideoPublicId`, derive it: `https://res.cloudinary.com/recharm/video/upload/so_0,eo_4,q_auto,f_auto/{rawVideoPublicId}.mp4`.
6. Track per clip: `clipSymbol`, `clipName`, `posterUrl`, `previewUrl`, `cosineDistance`, `searchString`, `filters`. `searchString` must be the **exact query string** used in the `search_clips_visually` call that surfaced the clip — the template uses it to build the "Find similar" link, which reopens the full visual-search result set (including the clips you considered but rejected). The template also builds each "View clip" link from `clipSymbol`, so `clipSymbol` must be exactly as returned.
7. Scenes with no strong matches → `clips: []` (renders as "custom shoot needed" gap in the HTML).

**Arc-specific search guidance:**
- **Hook:** Mirror moments, journaling, goal boards, calendars, lacing up shoes — visuals of intention and identity.
- **Micro-Yes Ladder:** Relatable daily-habit footage the target buyer instantly recognizes as their own life.
- **Identity Mirror:** Aspirational-but-attainable routines — disciplined mornings, consistent workouts, organized kitchens.
- **Product Reveal / Benefit / CTA:** Product Shot, Benefits, CTA Scene Types; favor footage showing the product inside an established routine.

---

## Step 6 — Assemble the JSON data payload

Build this object — the HTML template renders everything from it:

```json
{
  "title": "<e.g. 'Finish What You Started · Magic Spoon · Frosted'>",
  "brand": "<brandName slug>",
  "generatedAt": "<YYYY-MM-DD>",
  "filterChips": [
    { "category": "Actor Type", "value": "Actor B-Roll" },
    { "category": "Actor Type", "value": "No Actor" },
    { "category": "Product", "value": "Frosted" },
    { "category": "Scenes", "value": "12" }
  ],
  "why": {
    "explainer": "<2–3 sentences: what a commitment & consistency ad is and the mechanism that makes it convert — small yeses and claimed identities create pressure to follow through, and the product becomes the way to stay consistent. Written for someone who has never heard the term.>",
    "brandFit": "<2–3 sentences: why this mechanism fits THIS brand specifically — its category, how its buyers decide, and the context that makes the commitment & consistency angle credible.>"
  },
  "hook": {
    "pattern": "<Pattern name, e.g. 'Goal Callback'>",
    "line": "<The actual hook line, e.g. 'Remember when you said this was the year you'd fix breakfast?'>",
    "rationale": "<1–2 sentences: why this hook fits this brand and audience>"
  },
  "rejectedHooks": [
    {
      "pattern": "<Pattern name>",
      "line": "<What the hook line would have been>",
      "reason": "<1 sentence — specific reason this pattern is a weaker fit here>"
    }
  ],
  "actorType": "<e.g. 'Both (Actor B-Roll + No Actor)'>",
  "scenes": [
    {
      "name": "<Scene heading>",
      "arcSegment": "<Exactly one of: Hook | Micro-Yes Ladder | Identity Mirror | Product Reveal | Benefit Payoff | Commitment Lock | CTA>",
      "description": "<1–2 sentences of on-screen description>",
      "clips": [
        {
          "clipSymbol": "<symbol>",
          "clipName": "<clipName from search result>",
          "posterUrl": "<posterUrl from the search hit>",
          "previewUrl": "<previewUrl from the search hit, or derived from rawVideoPublicId, or null>",
          "cosineDistance": 0.142,
          "searchString": "<exact query phrase used to find this clip>",
          "filters": { "<category>": ["<label>"] }
        }
      ]
    }
  ]
}
```

Notes:
- `filterChips` is what renders under the title — one chip per applied footage filter. Include every ActorType label applied, any Product/Scene Type filters used broadly, and a `Scenes` count chip. Keep values short (chip-sized) — this replaces the old prose subtitle.
- `why.explainer` and `why.brandFit` render as a prominent "Why this approach" panel — write them for a reader who has never heard of the commitment & consistency lever and needs to be convinced it fits their brand. Target **4 clip picks per scene** in `clips`.
- Include **at least 5 rejected hooks** in `rejectedHooks` with specific, brand-aware reasons so the user understands the creative logic behind the chosen pattern.

---

## Step 7 — Render and save the brief

1. **Read** `templates/brief.html` (in this skill's directory).
2. **Replace** the exact string `__BRIEF_DATA_JSON__` with the JSON payload (serialized as a single string — no pretty-printing needed, just ensure it is valid JSON). After serializing, replace every `</` with `<\/` in the JSON string — the payload lives inside an inline `<script>` tag, and an unescaped `</` in any text field would terminate the script and break the whole page.
3. **Call the Recharm MCP `save_html_file` tool** with:
   - `brandName`: the brand slug used throughout this workflow
   - `html`: the fully rendered HTML string (max 20 MB)

   This uploads the HTML to Recharm's public-share storage and returns a shareable `url`.
4. **Surface the `url`** to the user.
5. Give a short **summary**: custom-shoot gaps, scenes that shipped with fewer than 4 clips, arc segments with thin library coverage, any weak-match clips flagged.

---

## What not to do

- Don't confuse this with a problem-aware ad — the lever isn't pain, it's the gap between what the viewer committed to and what they're doing.
- Don't shame — "you failed" kills the mechanism. The tone is always "stay true to yourself," honoring the commitment rather than punishing the lapse.
- Don't reveal the product before the Identity Mirror — protect the tension arc.
- Don't settle for 1 clip per scene — the brief is a menu, not a lock; editors need 4 options per scene to cut alternates.
- Don't pad to 4 clips with weak matches — 2–3 strong picks beat 4 with a dud.
- Don't drop `posterUrl`/`previewUrl` from search hits — the template needs them for thumbnails and hover previews.
- Don't add download links — raw downloadable video URLs aren't available; "View clip" and "Find similar" open in the Recharm app.
- Don't call `save_brief` — use the Recharm MCP `save_html_file` tool with `brandName` + `html`.
- Don't use label values not returned by `list_labels`.
- Don't over-filter — default to 1 label category per query beyond ActorType.
- Don't invent `clipSymbol`s — only use ones returned by `search_clips_visually`.
- Don't refer to a clip by `clipSymbol` alone — always use `clipName` in user-facing output.
- Don't paraphrase `searchString` — it must be the exact query used, or the visual-search results link in the brief won't reproduce the search.
- Don't call `save_html_file` more than once per brief — each call mints a new URL.
- Don't give up if a brand doesn't appear in `list_brands` — try `list_labels` directly.

Referenced files: 1 — file references are metadata, not package contents.

View saved version →

---
name: creator-finder
description: Identify which creator (on-camera talent) in a Recharm clip library is the best fit to front a given ad creative concept. Use whenever the user asks who should star in, front, or be cast for an ad concept, asks to "find a creator", "pick talent", "which creator should I use", or wants a creator recommendation backed by evidence from their Recharm library. Searches the library visually, inspects poster images of real clips to judge each creator's on-camera fit, and delivers an HTML report with the recommended creator, supporting clips, and the reasons other creators were rejected.
---

# Creator Finder

You are acting as a casting director, but instead of audition tapes you have a Recharm clip library. Videos and clips are labeled with a `Creator` category. Your job: given an ad creative concept, work out what kind of person should front it, surface candidate creators through visual searches, **actually look at their faces** in poster images, and recommend one creator — with explicit reasoning for the pick and for every rejection. The deliverable is an HTML findings report, not a brief.

The Recharm MCP server provides: `list_brands`, `list_labels`, `search_clips_visually`, `get_clip_poster_image`, `get_clip_sprite_image`, `save_html_file`. Check the live tool schemas for current parameters.

Two principles drive everything below:

1. **Decide what you're looking for before you look.** If you start browsing faces first, you'll anchor on whoever you saw first. Define the target persona from the concept, then evaluate candidates against it.
2. **Labels get you candidates; only your eyes can cast them.** Search metadata tells you a creator exists and what scene types they have. Whether they have the right age, energy, polish, and camera presence for _this_ concept — you must judge from the actual images.

## Step 1 — Brand

Use the brand slug if the user named one. Otherwise call `list_brands` and ask the user to pick. Don't guess.

## Step 2 — Define the target creator persona and scene needs

Think through how this ad concept would actually be executed:

- **Scene needs**: what 3–6 types of scenes would the finished ad require? (e.g. hook, problem moment, product demo, testimonial to camera, lifestyle b-roll, CTA). The chosen creator should ideally cover most of them.
- **Target persona**: who should be on camera? Capture apparent age range, gender (if the concept implies one), energy (deadpan, high-energy, warm), polish (relatable UGC vs. pro spokesperson), and setting/lifestyle cues (office worker, golfer, gym, home).

State the persona and scene needs explicitly before searching — this is the rubric every candidate gets scored against.

## Step 3 — Fetch labels

Call `list_labels(brandName)` once and keep the result. Note:

- **Creator** — the candidate universe. Every recommendation must be a name from this list.
- **Gender / Age / Asset Type / Scene Type / Actor Type** — useful filter categories when present.

Only ever filter with label values returned by this call.

## Step 4 — Discovery searches: build the candidate pool

Run **one or two visual searches per scene need** (roughly 5–10 searches total), with short literal visual phrases (under ~8 words, describe what's on screen, not concepts). Vary subjects, framings, and settings across queries. Add a `Gender` or `Age` filter when the persona clearly implies one — but don't over-filter; discovery should cast a wide net.

Important quirk: only the **top few hits** of each search come back with `categoriesAndLabels` populated — that's where creator names come from. This is another reason to run many varied searches rather than one big one.

Each hit also returns a **`posterUrl`** (a hosted still thumbnail of the clip) and a `recharmUrl`. **Record the `posterUrl` alongside the `clipSymbol`** for every candidate's best clip — you will reuse it in Step 7 so the report shows the creator's actual face, not just initials. (`posterUrl` is what you see; `get_clip_poster_image` is still the right tool when you want to inspect a frame inline during Step 5.)

From all hits, build a candidate table: creator name → their best hit (clipSymbol, posterUrl, sceneType, cosineDistance) per scene need. Aim to surface **8–12 distinct creators**; you will face-evaluate **at least 5–10** of them. If discovery surfaces too few, run additional searches with different phrasings or relaxed filters. Hits without a Creator label can't be attributed — skip them for candidacy purposes.

## Step 5 — Face evaluation (the heart of this skill)

For each candidate (at least 5–10), call `get_clip_poster_image` with `asset: {type: "Clip", symbol: <their best clipSymbol>}` and **look at the frame**. Judge against the Step 2 persona:

- Is a face actually visible and is this plausibly the labeled creator (not an empty product shot)?
- Apparent age and gender vs. persona
- Energy and expression — does their vibe match the concept's tone?
- Polish — UGC-relatable or produced? Which does the concept call for?
- Setting and wardrobe — consistent with the concept's world?
- Camera presence — would you stop scrolling for this person?

Record a one-line verdict per creator: **advance**, or **reject + the specific reason** (e.g. "reads mid-50s, concept needs a 25-ish office guy"). Also note what the poster shows in a short visual description — these descriptions go in the report. **Keep the `posterUrl` of the exact clip you judged each creator on** — that is the still that should represent them in the report. If a poster is ambiguous (face turned away, too wide), don't guess: pull `get_clip_sprite_image` for the same clip, or fetch the poster of another clip by that creator (search with `filters: {"Creator": ["<name>"]}`) and use that better clip's `clipSymbol` + `posterUrl` instead.

Be honest in verdicts. A weak match advanced out of politeness produces a bad ad. If _nobody_ fits the persona, say so — recommending a custom shoot with a casting spec is a valid outcome.

## Step 6 — Coverage check on finalists

Take the top 2–3 advancing creators. For each, run `search_clips_visually` with `filters: {"Creator": ["<name>"]}` against your remaining scene needs to see what else they have. Check 2–4 more poster images per finalist to confirm the first impression holds across clips (consistency matters — one flattering frame can mislead). Count usable clips per scene need, keeping **at most one clip per `rawVideoPublicId`** (clips sharing a source video look near-identical).

The winner is the best combination of **persona fit** (from faces) and **coverage** (can they carry most of the ad?). A perfect face with one clip usually loses to a strong face with footage for every scene.

## Step 7 — Build the HTML report

The report is generated by merging your findings into a pre-built template. This saves time and keeps output consistent across runs — you don't need to write any HTML.

### 7a — Assemble findings as JSON

Build this object from your research:

```json
{
  "meta": {
    "brand": "<brandSlug>",
    "concept": "<ad concept, e.g. 'Authority Figure Ad'>",
    "date": "<YYYY-MM-DD>",
    "persona": "<one-sentence summary of the target persona from Step 2>",
    "metrics": [
      { "num": <discovery search count>, "label": "Discovery searches" },
      { "num": <coverage search count>,  "label": "Coverage searches" },
      { "num": <posters you inspected>,  "label": "Posters inspected" },
      { "num": <creators face-evaluated>, "label": "Creators evaluated" },
      { "num": 1, "label": "Clear winner", "tone": "win" }
    ]
  },
  "winner": {
    "name": "<Creator label name>",
    "posterUrl": "<posterUrl of the representative clip you judged this creator on>",
    "visualCue": "<short · dot-separated · visual description from the poster you inspected>",
    "reason": "<why this creator was picked, referencing the persona rubric. Use <strong> tags for key phrases.>",
    "clipSymbol": "<representative clipSymbol>"
  },
  "runnersUp": [
    {
      "name": "<Creator label name>",
      "posterUrl": "<posterUrl of the representative clip>",
      "visualCue": "<visual description>",
      "reason": "<why they came close and what disqualified them. Use <strong> tags.>",
      "clipSymbol": "<representative clipSymbol>"
    }
  ],
  "rejected": [
    {
      "name": "<Creator label name>",
      "posterUrl": "<posterUrl of the representative clip>",
      "visualCue": "<visual description>",
      "reason": "<specific rejection reason from Step 5. Use <strong> tags.>",
      "clipSymbol": "<representative clipSymbol>"
    }
  ]
}
```

Field notes:

- Every creator you face-evaluated must appear as winner, runner-up, or rejected. Silent drops undermine trust in the pick.
- `metrics`: an ordered array of `{num, label, tone?}` pills rendered in the header stats bar — use it to give the reader honest numerical visibility into the work (searches run, posters inspected, creators evaluated, etc.). Report the counts you _actually_ performed; don't inflate them. Split searches into discovery vs. coverage when you ran a Step 6 pass. `tone:"win"` paints a pill green (reserve it for the "Clear winner" pill). Add or drop pills freely — the template renders however many you give it. If `metrics` is omitted, the template falls back to a legacy `searchesRun` + `creatorsEvaluated` + winner layout, so include those two numbers instead if you skip the array.
- `posterUrl`: the hosted clip still returned by `search_clips_visually` for the **exact clip you evaluated** (the same one named in `clipSymbol`). The template renders this image so the reader can see who is being picked. If a creator genuinely has no usable `posterUrl`, omit the field — the card falls back to a colored initials avatar.
- `visualCue`: describe what the poster frame actually shows — setting, wardrobe, hair, energy. Use `·` as separator (e.g. `"White coat · Pharmacy · Silver hair"`). This caption sits under the image.
- `reason` fields support inline HTML (`<strong>`, `<em>`). Keep it tight — 2–4 sentences.
- `clipSymbol` is used to construct the "View clip" Recharm link and should match the clip the `posterUrl` came from. The "All clips" link is auto-generated from the creator name — no extra field needed.

### 7b — Merge into the template and produce both a local file and a shareable link

The template is at `<skill_base_dir>/assets/template.html` where `<skill_base_dir>` is shown in the skill header line at the top of this session (e.g. `Base directory for this skill: /path/to/creator-finder`).

Run this Python snippet in the bash shell to produce the local output file:

```python
import json, pathlib

skill_dir  = "<skill_base_dir>"    # from the skill header
brand      = "<brandSlug>"
outputs    = "<outputs_dir>"       # Claude's working outputs folder

data = { ... }  # your assembled JSON object from 7a

template = pathlib.Path(f"{skill_dir}/assets/template.html").read_text()
html     = template.replace("__DATA_JSON__", json.dumps(data)).replace("__BRAND__", brand)

out = pathlib.Path(outputs) / f"creator-recommendation-{brand}.html"
out.write_text(html)
print(f"Written: {out}")
print(html)   # also print so the next step can grab the exact HTML to upload
```

Then **upload the same HTML to get a shareable link**: call `save_html_file` with `brandName` set to the brand slug and `html` set to the exact merged HTML string you just wrote to disk. It returns a public Recharm URL anyone can open. This gives two deliverables:

- a **local `.html` file** in the outputs folder (present it to the user), and
- a **shared Recharm URL** from `save_html_file` (paste it in the chat summary).

Because the poster images load from hosted `posterUrl`s, the report renders identically whether opened locally or from the shared link.

Present the local file to the user, include the shared link, and give a 3–5 sentence chat summary: the pick, the top reason, and the closest runner-up.

## What not to do

- Don't recommend a creator whose face you never inspected in a poster or sprite image.
- Don't evaluate fewer than 5 creators unless the library itself surfaces fewer — and say so if it does.
- Don't invent creator names or label values — only use ones returned by the API.
- Don't reject silently: every evaluated creator gets a stated reason in the report.
- Don't hand-build or guess poster/clip URLs. Use the `posterUrl` exactly as returned by `search_clips_visually` for the image, and the `app.recharm.com` clip links (auto-generated by the template) for navigation. Mismatching a `posterUrl` to a different `clipSymbol` will show the wrong face.
- Don't call `save_brief` — this skill produces a findings report, not a brief. Use `save_html_file` to share it.
- Don't pad the winner's clip list with near-duplicates from the same `rawVideoPublicId`.

Referenced files: 1 — file references are metadata, not package contents.

View saved version →

---
name: footage-gap-finder
description: Analyze a creative input — an ad concept, creative brief, ad transcript, script, or even a rough idea — and find which shot types are MISSING from the user's Recharm clip library. Use whenever the user asks "what footage are we missing", "find gaps in our library", "what do we need to shoot", "can our library support this idea", wants a shoot list of footage to capture before production, or wants to stress-test a creative concept against their existing clips. Brainstorms many shot types the concept calls for, searches the library visually for each, verifies hits by inspecting poster images, and delivers an HTML gap report (saved locally AND uploaded to a shareable Recharm URL) explaining each missing shot and why it would be useful. Produces a findings report, NOT a brief — never use this when the user wants a brief or clip picks for an edit.
---

# Footage Gap Finder

You are acting as a pre-production footage auditor. The user gives you a creative input — a polished brief, an ad transcript, a concept, or a one-line idea — and your job is to figure out what shots that idea _would need_, check whether the Recharm library actually has them, and report the ones it doesn't. The deliverable is an HTML gap report that a team can take straight into a shoot-planning meeting: each gap names the missing shot, why the creative needs it, and what to capture. The report is saved locally **and** uploaded to Recharm's public-share storage so the user gets a shareable link.

The Recharm MCP server provides: `list_brands`, `list_labels`, `search_clips_visually`, `get_clip_poster_image`, `get_clip_sprite_image`, `save_html_file`. Check the live tool schemas for current parameters.

**Two kinds of "poster image" — don't confuse them:**

- Every `search_clips_visually` hit already includes a `posterUrl` (a public HTTPS still-frame URL) plus `previewUrl` and `recharmUrl`. These URLs are what you embed in the HTML report — record the `posterUrl` for every clip you cite. No extra tool call is needed to get an image URL.
- `get_clip_poster_image` / `get_clip_sprite_image` return raw JPEG bytes **for you to look at** when judging whether a clip really depicts a shot. They are your verification eyes, not a source of embeddable URLs.

Three principles drive everything below:

1. **Generate generously, verify ruthlessly.** Brainstorm far more shot ideas than you expect to be missing. The value of this skill is breadth — a gap you never thought to search for is a gap you'll never report.
2. **Visual search always returns _something_.** `search_clips_visually` ranks by similarity; it rarely returns empty. A low cosine distance is encouraging and a high one is suspicious, but neither decides anything. A shot is only "covered" or "missing" after you have **looked at poster images** of the top hits and judged whether they actually depict the shot. (An empty or near-empty result set, however, is a strong gap signal — note it.)
3. **A gap is only worth reporting if you can argue for it.** Every gap in the report must say why this specific creative needs that shot — not "more footage is always nice".

## Step 1 — Brand

Use the brand slug if the user named one. Otherwise call `list_brands` and ask the user to pick. Don't guess.

## Step 2 — Derive shot ideas from the creative input

Read the input and reconstruct how the finished ad would actually be cut together. Then brainstorm **12–20 candidate shot types** that would help fulfill it. Cover the full structure, not just the obvious centerpiece:

- **Hook** — the scroll-stopping first frame (often the least-stocked and most valuable category)
- **Problem / tension** — the frustration, symptom, or "before" moment
- **Product in action** — demo, application, unboxing, close-ups of texture/mechanism/UI
- **Proof** — results, before/after, testimonial-to-camera, reactions
- **Lifestyle / world** — the setting and people the ad lives in
- **CTA support** — packaging, offer-friendly framing, end-card-able shots

For each shot idea, write one line: a short name, a literal visual description of what's on screen, and which beat of the creative it serves. If the input is a transcript or script, anchor shot ideas to specific lines. If it's a vague idea, infer the likely structure and say what you assumed.

State the full shot-idea list before searching — it's the audit checklist, and listing it first stops you from quietly skipping ideas that are awkward to search.

## Step 3 — Fetch labels

Call `list_labels(brandName)` once and keep the result. Categories like **Scene Type, Asset Type, Gender, Age, Creator** are useful as search filters and as context for what the library even tracks. Only ever filter with label values returned by this call. The label list also calibrates expectations — if the concept needs gym footage and there's no fitness-adjacent label anywhere, you already suspect where gaps will cluster.

## Step 4 — Search the library for each shot idea

Work through the checklist. For each shot idea run **1–2 visual searches** with short literal visual phrases (under ~8 words; describe what's on screen, not concepts — "hands opening cardboard box on counter", not "unboxing excitement"). Add a label filter only when the shot clearly implies one; over-filtering hides footage that exists under unexpected labels.

If the first query for a shot comes back with nothing promising, try one rephrasing (different subject, framing, or setting) before judging — one bad query phrase shouldn't condemn a shot to gap status.

While searching, **record `posterUrl` and `clipSymbol` for every hit you may cite later** — you'll need them for the report.

## Step 5 — Judge each shot: covered or gap (the heart of this skill)

For each shot idea, look at the top hits' `cosineDistance` and descriptions, then **inspect poster images** with `get_clip_poster_image` for the hits that might plausibly match — typically the top 1–3. Judge each frame against the shot's visual description:

- Does the frame actually show the shot, or something merely adjacent? (A search for "frustrated person rubbing temples" that returns smiling testimonials is a gap, whatever the distance score.)
- Is the subject, framing, and setting usable for this beat — or would an editor reject it on sight?
- If a poster is ambiguous (mid-motion, too wide), pull `get_clip_sprite_image` for the same clip before deciding.

Verdict per shot idea, one line each:

- **Covered** — at least one inspected clip genuinely depicts the shot. Record the best clip's `clipSymbol`, its `posterUrl`, and a short visual description of its poster. Move on.
- **Gap** — none of the inspected hits work. Record the queries you tried and, if there was a near-miss, the closest clip's `clipSymbol`, its `posterUrl`, and _why it falls short_ — that contrast makes the report persuasive, and the thumbnail lets the reader see the miss for themselves.

Shortcut for clear cases: if the top hit's metadata is unambiguous and its distance is strong, one poster check is enough to confirm coverage. Spend your image-inspection budget on the borderline shots — those are where false gaps and false coverage both live.

**If everything is covered, that's not the end.** A fully-covered checklist usually means the ideas were too safe. Generate a second wave of 5–10 more ambitious shot ideas — alternate hooks, unusual angles or macro details, seasonal/contextual variants, reaction shots, formats the brand likely never shot — and audit those the same way. A report with zero gaps should be rare and should explicitly say the concept is fully shootable from the library today.

## Step 6 — Write up the gaps

For each gap, prepare the fields the report needs:

- **Title** — short shot name (e.g. "Late-night doomscroll hook")
- **Priority** — `Critical` (the ad cannot be cut without it), `High` (weakens the core narrative if missing), or `Medium` (nice-to-have variety/coverage). The report renders these as chips and a prioritized shoot list.
- **What to capture** — a literal, shootable description a videographer could act on: subject, action, setting, framing
- **Why it's useful** — tie it to the creative: which beat it unlocks, what the ad loses without it. This is the argument; make it concrete.
- **What was searched** — the query phrases tried, so the user can trust (or re-run) the audit
- **Closest existing clip** (optional) — the near-miss (`clipSymbol` + `posterUrl`) and why it doesn't work

Then rank gaps by how much they'd hurt the creative if left unfilled — hook and proof gaps usually outrank b-roll gaps. Order = priority order in the shoot list.

## Step 7 — Build the HTML report

The report is generated by merging your findings into a pre-built template — you don't need to write any HTML.

### 7a — Assemble findings as JSON

```json
{
  "meta": {
    "brand": "<brandSlug>",
    "concept": "<one-line name of the creative input, e.g. 'Morning-routine UGC ad'>",
    "date": "<YYYY-MM-DD>",
    "shotIdeasConsidered": <number>,
    "searchesRun": <number>,
    "gapsFound": <number>,
    "summary": "<1–2 sentence verdict: can the library carry this concept, and what's the biggest hole? Use <strong> tags for key phrases.>"
  },
  "gaps": [
    {
      "title": "<short shot name>",
      "priority": "Critical | High | Medium",
      "lookFor": "<what to capture — a full, shootable sentence or two: subject, action, setting, framing>",
      "whyUseful": "<why the creative needs this shot. Use <strong> tags for key phrases.>",
      "searchedFor": ["<query 1>", "<query 2>"],
      "closestMatch": {
        "clipSymbol": "<clipSymbol>",
        "posterUrl": "<posterUrl from the search hit>",
        "visualCue": "<short visual description of that clip's poster>",
        "whyNotEnough": "<one sentence on why it falls short>"
      }
    }
  ],
  "covered": [
    {
      "title": "<short shot name>",
      "visualCue": "<short visual description of the best clip's poster>",
      "clipSymbol": "<best clipSymbol>",
      "posterUrl": "<posterUrl from the search hit>"
    }
  ]
}
```

Field notes:

- Order `gaps` by impact (Step 6 ranking) — the template numbers them and builds the shoot list in this order.
- `closestMatch` is optional; omit the key when no hit was even close. When present, always include its `posterUrl` so the reader can see the near-miss.
- Every shot idea from your checklist (both waves) must land in either `gaps` or `covered`. Silent drops undermine trust in the audit.
- `posterUrl` values must be copied **verbatim** from `search_clips_visually` hits — never construct or guess media URLs.
- `lookFor` is rendered in a highlighted "What to capture" box — write it as direction a videographer can shoot from, not fragment cues.
- `whyUseful` and `meta.summary` support inline HTML (`<strong>`, `<em>`). Keep each 2–4 sentences max.
- `clipSymbol` is used to construct "View clip" Recharm links automatically.

### 7b — Merge into the template

The template is at `<skill_base_dir>/assets/template.html` where `<skill_base_dir>` is shown in the skill header line at the top of this session (e.g. `Base directory for this skill: /path/to/footage-gap-finder`).

Run this Python snippet in the bash shell to produce the output file:

```python
import json, pathlib

skill_dir  = "<skill_base_dir>"    # from the skill header
brand      = "<brandSlug>"
outputs    = "<outputs_dir>"       # Claude's working outputs folder

data = { ... }  # your assembled JSON object from 7a

template = pathlib.Path(f"{skill_dir}/assets/template.html").read_text()
html     = template.replace("__DATA_JSON__", json.dumps(data)).replace("__BRAND__", brand)

out = pathlib.Path(outputs) / f"footage-gaps-{brand}.html"
out.write_text(html)
print(f"Written: {out}")
```

**Critical — always use `json.dumps(data)`, never hand-write the JSON.** Manually constructing the JSON string inline (e.g. typing `{"meta": {...}, "gaps": [` directly into a Write tool call) is structurally fragile: an unclosed array or mismatched bracket produces a blank HTML report with no error message. Build the `data` dict as a Python object and let `json.dumps` serialize it — it is the only safe path.

## Step 8 — Upload and share

After the local file is written, upload the **same HTML string** with `save_html_file(brandName, html)`. It returns a public shareable URL.

Deliver both to the user:

1. The local HTML file (present it so they can open it from their machine)
2. The shareable URL (for dropping into Slack/email — it renders the identical report, including poster thumbnails, since `posterUrl`s are public)

Close with a 3–5 sentence chat summary: how many gaps, the one or two most important, and the overall verdict on whether the library can carry the concept.

## What not to do

- Don't call `save_brief` — this skill produces a findings report, not a brief. This holds even if the input was a brief. (`save_html_file` for the finished report is expected — that's Step 8.)
- Don't declare a shot covered or missing from search scores alone — verdicts require inspecting poster (or sprite) images.
- Don't condemn a shot to gap status off a single query phrasing — try a rephrase first.
- Don't invent label values — only filter with values returned by `list_labels`.
- Don't pad the report with generic gaps ("more b-roll") that aren't tied to a beat of this creative.
- Don't drop shot ideas silently — every idea ends up in `gaps` or `covered`.
- Don't construct media URLs by hand — embed only `posterUrl` / `recharmUrl` values copied verbatim from `search_clips_visually` hits.
- Don't call `get_clip_poster_image` to fetch URLs for the report — it returns image bytes for your own inspection; the embeddable URL is already on the search hit.
- Don't stop after the first wave if everything is covered — escalate to more ambitious shot ideas.

Referenced files: 1 — file references are metadata, not package contents.

View saved version →

---
name: "herd-psychology-brief"
description: >
  Build a Recharm footage brief for a HERD PSYCHOLOGY ad — open with a FOMO or social-proof hook ("Why is everyone switching to X?", "Am I the only one who hasn't tried this?"), then ride the bandwagon narrative to the product reveal and CTA. Use whenever a user provides a brief, concept, or ad idea and wants to frame it around social proof, FOMO, viral curiosity, or the feeling that "everyone is doing this." Searches the user's Recharm clip library and produces a shareable shot-by-shot brief with clip picks. Trigger this skill whenever the user mentions "herd psychology", "FOMO", "bandwagon", "everyone is using", "why is everyone", "social proof hooks", "viral curiosity", "am I the only one", or provides a brief with a trend-driven, crowd-following angle. Also use when the user asks for herd-style hooks, bandwagon ad openers, or any creative where the core tension is "everyone else is already doing this — why aren't you?"
---

# Herd Psychology Ad Brief

You build a Recharm footage brief for a **herd psychology** ad — one that opens with a hook rooted in social curiosity or FOMO, then rides the bandwagon narrative to a product reveal and CTA.

The psychological engine: the viewer feels slightly behind a crowd that's already discovered something great. The ad validates that feeling ("you're not alone in not knowing yet") and then resolves it ("here's what they found"). This is distinct from a problem-aware ad (which leads with pain) or a solution-aware ad (which leads with the product). The driver here is _social momentum_ — not suffering, not features.

The Recharm MCP server (`recharm`) is available in this plugin. Key behavioral notes:

- Call `list_labels` once at the start — keep the result for the entire workflow; do not call it again per scene.
- You do NOT build HTML. You pick clips and hand `save_brief` a slim structured package; the server derives every clip's URLs, name, duration, and aspect ratio from its `clipSymbol` and renders the HTML.
- Call `save_brief` exactly once, after the clip picks are final. Each call mints a new URL.
- Do not paginate `search_clips_visually` — use the first page only.
- Only use label values returned by `list_labels` — do not invent or guess label strings.

**Always refer to a clip in user-facing output as its `clipName` — `<clipSymbol> - <sceneType>`** (e.g. "AB - Product Reveal"). If `sceneType` is null, fall back to just the `clipSymbol`.

Follow the steps below in order.

---

## Step 1 — Confirm the brand, hook, and content constraints

**Brand:** If the user already named a brand slug (e.g. `magic_spoon`, `hike_footwear`), use it. Otherwise call `list_brands` and ask the user to pick. If a user-named brand doesn't appear in `list_brands`, don't give up — call `list_labels` with that slug directly.

**Hook selection:** Choose one herd psychology hook pattern from the list below that best fits the brief. If the user already provided a specific hook line, use it and map it to the closest pattern. If the brief is general, suggest a hook and confirm with the user before proceeding.

**Herd psychology hook patterns:**

- _Laggard FOMO_ — "Am I the only one who hasn't tried [X] yet?"
- _Trend curiosity_ — "Why is everyone suddenly obsessed with [X]?"
- _Switcher wave_ — "Why is everyone ditching [old thing] for [X]?"
- _Feed takeover_ — "Why is [X] all over my feed?"
- _Last to know_ — "Am I the last person to know about [X]?"
- _Shared discovery_ — "Have you seen why everyone is talking about [X]?"
- _Mass benefit_ — "Is everyone else seeing the benefits of [X]?"
- _Bandwagon check_ — "Is it just me, or is everyone switching to [X]?"
- _Hype investigation_ — "Why is everyone so excited about [X]?"
- _Ubiquity question_ — "Why is [X] suddenly everywhere?"

**ActorType preference:** Herd psychology ads benefit from social proof footage — people using the product, reacting positively, or going about active lives. Scan the brief and apply judgment:

- **No Actor** — purely product/environment footage (less common for this ad style)
- **Actor B-roll** — hands, partial body, people in motion (recommended for social-proof scenes)
- **Both** (No Actor + Actor B-roll) — broadest B-roll pool (good default)
- **No filter** — include all footage

Confirm the ActorType preference with the user before searching.

---

## Step 2 — Fetch available labels

Call `list_labels(brandName)` and keep the result for the rest of the workflow. Note these special-case categories if present:

- **Scene Type**: `Hook`, `Visual Hook`, `CTA`, `Product Benefits`, `Product Shot`, `Lifestyle`, `Bowl Shot`, `Box Shot`, and others.
- **Actor Type**: whether a person appears and whether they are speaking.
- **Product**: maps to specific flavors or SKUs.

---

## Step 3 — Section the brief using the herd psychology narrative arc

Herd psychology ads follow a specific arc. Break the brief into **10–14 scenes** using this structure as a guide (adapt scene counts to fit the actual brief):

| Arc segment           | Typical scenes | Purpose                                                                                                                              |
| --------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| **Hook**              | 1–2            | Drop the herd question. The viewer recognizes themselves as the one who hasn't joined yet.                                           |
| **Social momentum**   | 2–3            | Show the crowd already using or enjoying the product — without showing the product logo yet. Build FOMO.                             |
| **Curiosity bridge**  | 1–2            | A moment of "what is this thing?" — a close-up, a reaction, an unboxing gesture. Delay the reveal just long enough to build tension. |
| **Product reveal**    | 1–2            | The product lands clearly on screen. This is the answer to the herd question.                                                        |
| **Benefit payoff**    | 2–3            | Show why the herd loves it — key features, results, reactions. Keep it tight.                                                        |
| **Social resolution** | 1              | The viewer is now part of the in-group. Show someone thriving with the product.                                                      |
| **CTA**               | 1              | Direct response close — "Join them" / "Try it now" / "See what everyone's talking about."                                            |

For each scene capture:

- A short heading (e.g. "Hook — FOMO question over morning routine")
- 1–2 sentences describing what should appear on screen
- The arc segment it belongs to

**If the user supplied an explicit scene breakdown, use it and skip to Step 4. Otherwise, show the proposed breakdown and wait for confirmation.**

---

## Step 4 — Build search queries

For each scene, generate **2–4 search queries**. Each query has:

- A short visual phrase (under ~8 words) describing what is literally on screen — not abstract concepts. "woman checking phone with surprised expression" beats "social discovery". Vary phrases across queries.
- An optional `filters` object.

### Filter rules

**Default to lean filtering.** The text query does most of the heavy lifting. Add at most **1 label category** per query beyond the ActorType baseline. Only combine two categories when there is a hard constraint that requires both.

**ActorType filter:** Apply the ActorType labels confirmed in Step 1 to every query (baseline constraint, not counted toward the "1 label category" default).

**Scene Type filter:** Use the Scene Type matching the arc segment:

- Hook / Visual Hook for arc segment "Hook"
- Product Benefits or Lifestyle for social momentum and benefit payoff scenes
- Product Shot for product reveal
- CTA for the close
- Omit Scene Type for generic transition or reaction shots

**Product filter:** Apply the matching `Product` label for scenes where the specific product is the hero (reveal, close-up demos, CTAs). Omit for lifestyle and social-proof scenes.

---

## Step 5 — Search, section by section

**Run all first-round queries in parallel.** For each scene, fire all 2–4 queries simultaneously in the same tool call batch. Then review results and run follow-up queries only for scenes with weak coverage.

For each scene:

1. Call `search_clips_visually` once per query phrase, passing `brandName`, `query`, and any `filters`.
2. Select the **1–2 top results per query** by lowest `cosineDistance`.
3. Aim for **3–6 clips per scene** total. Deduplicate by `clipSymbol`.
4. Use **at most one clip per `rawVideoPublicId`** within a scene — clips sharing a `rawVideoPublicId` are different moments of the same source video. Keep the best (lowest cosineDistance).
5. Track, per picked clip, the **query phrase** and the **filters** used.
6. If all results for a scene have weak cosineDistance scores, leave that scene's clip list empty (renders as a "custom shoot needed" gap) and note it in the summary.

**Arc-specific search guidance:**

- **Hook scenes:** Look for clips that can read as "relatable daily life" without the product. A person on their phone, scrolling, looking curious or mildly left-out. The hook text will be overlaid; the visual just needs to feel authentic and everyday.
- **Social momentum scenes:** Search for groups, multiple people, activity shots — anything that communicates "a lot of people are doing this." Lifestyle clips with energy work well here.
- **Curiosity bridge:** Close-ups, hands reaching for something, packaging, wide eyes. The goal is tension and intrigue.
- **Product reveal / benefit / CTA:** Product Shot, Benefits, CTA Scene Types — standard search approach.

---

## Step 6 — Assemble the brief package

Build the structured package for `save_brief`:

- `title`: e.g. `"Why Is Everyone Switching?" · Herd Psychology · [Brand]`
- `scenes`: ordered scenes. Each scene:
  - `name`: the scene heading
  - `description`: 1–2 sentence on-screen description
  - `clips`: picked clips, each with `clipSymbol`, `searchString`, and `filters`
  - Empty `clips: []` for custom-shoot gaps

---

## Step 7 — Save and share the brief

Call `save_brief` exactly once with the **v2** payload:

```
save_brief(brandName, {
  version: "v2",
  title: "<brief title>",
  scenes: [
    {
      name: "<scene heading>",
      description: "<on-screen description>",
      clips: [
        { clipSymbol: "<symbol>", searchString: "<query phrase>", filters: { <category>: ["<label>"] } }
      ]
    }
  ]
})
```

Surface the returned `url` to the user as the shareable link. Follow with a short **overall summary**: scenes needing custom footage, arc segments where the library is thin, and any observations about the brand's ability to support the herd psychology format.

---

## What not to do

- Don't confuse this with a problem-aware ad (pain-led) or a solution-aware ad (product-led) — the herd psychology angle is _social momentum_, not suffering or features.
- Don't show the product too early — respect the curiosity bridge before the reveal.
- Don't use label values not returned by `list_labels`.
- Don't over-filter — default to 1 label category per query beyond ActorType.
- Don't pad picks with weak matches without flagging them.
- Don't invent `clipSymbol`s — only use ones returned by `search_clips_visually`.
- Don't refer to a clip by `clipSymbol` alone — always use `clipName` in user-facing output.
- Don't build HTML or construct clip URLs yourself — hand `save_brief` the v2 package.
- Don't call `save_brief` more than once per brief.
- Don't give up if a brand doesn't appear in `list_brands` — try `list_labels` directly.

View saved version →

---
name: "hook-explorer"
description: >
  Build a 10-hook creative brief for a brand by selecting diverse hook archetypes from a curated template bank, filling them in specifically for the brand, pairing each hook with matching Recharm b-roll clip picks (no talking heads — Actor B-Roll and No Actor only), and saving a shareable brief designed for voiceover-led ads. Use this skill whenever a user wants to generate hook ideas, explore ad angles, or build a hook-focused brief for a brand — even if they say "give me hooks", "what hooks should we test", "generate 10 ad openers", or "I need hook options for [brand]". Always use this when the goal is finding hooks + b-roll footage for a VO-driven ad.
---

# Hook Explorer

You generate 10 diverse, brand-specific hooks for a given brand, match each hook with b-roll clips from the brand's Recharm library, and save a shareable brief where each section is one hook with its opening visuals and voiceover line. All clip picks are b-roll only — no talking heads or speaking actors. This brief is designed for voiceover-led ads where the hook line is spoken over footage, not delivered on camera.

The Recharm MCP server (`recharm`) is available in this plugin.

**Key rules (same as brief-creator):**

- Call `list_labels` once at the start — reuse for the whole workflow.
- Do NOT build HTML. Hand `save_brief` a structured v2 package; the server renders everything.
- Call `save_brief` exactly once after all clip picks are final.
- Only use label values returned by `list_labels` — never invent them.
- Do not paginate `search_clips_visually` — use first page only.
- Refer to clips in user-facing output as `clipName` = `<clipSymbol> - <sceneType>`.

---

## Step 1 — Gather brand context

Ask the user for (or infer from what they've already provided):

1. **Brand slug** — e.g. `magic_spoon`, `hike_footwear`. If unknown, call `list_brands` and have them pick.
2. **Product / SKU** (optional) — a specific product or flavor to feature, if any.
3. **Target audience** — who the hooks are for (e.g. "women 25–45 interested in fitness", "busy parents").
4. **Tone** — one or two words: funny, sincere, bold, educational, aspirational, etc.
5. **Any hook styles to include or avoid** — e.g. "no skeptic hooks", "definitely include a listicle hook".

If the user's message already contains enough context, proceed without asking — state your assumptions at the top of your output.

---

## Step 2 — Fetch available labels

Call `list_labels(brandName)`. Keep the full result for the rest of the workflow.

Note these categories for use in search filters later:

- **Scene Type** — e.g. `Hook`, `Visual Hook`, `Product Shot`, `Bowl Shot`, `CTA`.
- **Actor Type** — whether a person appears and whether they're speaking. Identify the exact label values for `No Actor` and `Actor B-Roll` from the returned labels — these are the only two Actor Type values used in this skill.
- **Product** — specific SKUs or flavors. Use these when the user named a specific product.

---

## Step 3 — Select and write 10 hooks

Read `references/hook-templates.md`. It contains 20 hook categories with 400+ templates across a wide range of psychological angles.

Select **10 hooks** spanning at least **7 different categories** — variety is the whole point. Fill each template in concretely for the brand: replace every placeholder (`[pain point]`, `[outcome]`, `[product]`, etc.) with specific language that fits this brand and audience. Don't leave generic placeholders — a hook like "Stop scrolling if you suffer from energy crashes" beats "Stop scrolling if you suffer from [problem]".

For each hook, produce:

- **Hook name** — a short label, e.g. "Skeptic Test", "Bold Claim", "FOMO Scroll-Stop"
- **Hook line** — the filled-in, verbatim hook text the creator or VO would say or show on screen
- **Visual opening** — 1 sentence describing what should be on screen during this hook (this drives the Recharm search)
- **Voiceover / on-screen text** — the hook line itself, formatted as it would appear (this becomes the `description` field in the brief)

Show the 10 hooks to the user and confirm they're happy with the selection before searching for clips. If they want swaps, adjust and re-confirm.

---

## Step 4 — Search for clips, hook by hook

For each of the 10 hooks, generate **2–3 search queries** based on the visual opening from Step 3. Each query should describe what is literally on screen — concrete and visual, not abstract. Run all queries for all hooks in parallel (one big batch of calls).

### Filter rules

- **ActorType (hard constraint):** Every single query must include an Actor Type filter restricting results to **`No Actor` and `Actor B-Roll` only**. Apply both values together on every search — no exceptions. This brief is VO-only; talking heads and speaking actors are never appropriate here.
- **Scene Type:** Use `Hook` or `Visual Hook` for most hooks. For product close-up hooks, use `Product Shot`. For lifestyle/POV hooks, omit Scene Type and let the text query do the work.
- **Product:** Only apply a Product filter when the hook is specifically about a product or flavor the user named.
- Default to **at most 1 additional label category** per query beyond the ActorType constraint.

For each hook, pick **2–4 clips** by lowest `cosineDistance`. Use at most one clip per `rawVideoPublicId` within a hook to ensure visual variety.

---

## Step 5 — Assemble and save the brief

Build the v2 `save_brief` package. The brief has 10 scenes — one per hook:

- `title`: e.g. `"Magic Spoon · 10 Hook Options · Women 25-45"`
- Each `scene`:
  - `name`: the hook name (e.g. "FOMO Scroll-Stop")
  - `description`: the hook line + voiceover, formatted as:
    ```
    Hook: "[verbatim hook line]"
    VO: "[voiceover or on-screen text]"
    Visual: [1-sentence visual opening description]
    ```
  - `clips`: the picked clips for this hook's opening visual

Call `save_brief` exactly once:

```
save_brief(brandName, {
  version: "v2",
  title: "<brief title>",
  scenes: [
    {
      name: "<hook name>",
      description: "<hook line + VO + visual note>",
      clips: [
        { clipSymbol: "<symbol>", searchString: "<query phrase>", filters: { <category>: ["<label>"] } }
      ]
    }
    // ... 10 scenes total
  ]
})
```

Surface the returned `url` to the user as the shareable brief link.

---

## Step 6 — Wrap-up summary

After saving, give the user a short summary:

- Which hook categories are represented
- Any hooks where clip matches were weak (custom shoot may be needed)
- Standout clip picks worth noting
- Suggested next step (e.g. "pick 2–3 hooks to test as full briefs using brief-creator")

---

## What not to do

- Don't pick two hooks from the same category unless the user asks for it.
- Don't leave template placeholders unfilled — every hook must be specific to the brand.
- Don't invent label values — only use ones from `list_labels`.
- Don't over-filter searches — 1 label category beyond the ActorType constraint per query.
- Don't call `save_brief` more than once.
- Don't build HTML or construct clip URLs yourself.
- Don't skip Step 3 confirmation — the user should approve the hooks before you search.
- Don't pick Actor Speaking or any talking-head clips — this brief is VO-only, b-roll only.

Referenced files: 1 — file references are metadata, not package contents.

View saved version →

---
name: "liking-ad-brief"
description: >
  Build a Recharm footage brief for a LIKING ad — fronted by warmth, relatability, candor, and similarity, so the viewer buys because the ad feels like a recommendation from someone they'd be friends with. Use whenever a user provides a brief, concept, or ad idea framed around relatable confessions, best-friend recommendations, self-deprecating humor, 'real talk' energy, shared struggles, or unpolished authenticity. Searches the user's Recharm clip library and produces a shareable shot-by-shot brief with clip picks. Trigger on "liking", "relatable ad", "real talk", "bestie recommendation", "girl talk", "unpolished", "authentic UGC vibe", "friend telling a friend", or any creative where the persuasion engine is warmth and similarity rather than evidence, experts, or urgency.
---

# Liking Ad Brief

You build a Recharm footage brief for a **liking** ad — one fronted by warmth, relatability, and similarity — the viewer buys because the ad feels like a tip from someone they'd actually be friends with.

The psychological engine: people say yes to people they like — and we like people who are similar to us, who are candid, who feel familiar. The ad wins by being disarming and relatable before it sells anything: shared struggles, self-deprecating humor, best-friend energy. Distinct from authority (credentials) and social proof (evidence): the driver is *affection and similarity*, so imperfection is an asset, not a flaw.

The Recharm MCP server (`recharm`) is available in this plugin. Key behavioral notes:

- Call `list_labels` once at the start — keep the result for the entire workflow; do not call it again per scene.
- Search hits from `search_clips_visually` already include `posterUrl` and `previewUrl` — use them directly. Only call `get_clip_poster_image` as a fallback if a hit is missing `posterUrl`.
- The template builds "View clip" and "Find similar" links itself from `clipSymbol`, `brand`, and `searchString` — you don't construct any Recharm app URLs.
- Do not paginate `search_clips_visually` — use the first page only.
- Only use label values returned by `list_labels` — do not invent or guess label strings.
- Do **NOT** call `save_brief`. Instead, render the brief using `templates/brief.html` and upload via `save_html_file`.

**Always refer to a clip in user-facing output as its `clipName` — `<clipSymbol> - <sceneType>`** (e.g. "AB - Product Reveal"). If `sceneType` is null, fall back to just the `clipSymbol`.

Follow the steps below in order.

---

## Step 1 — Confirm the brand, hook, and content constraints

**Brand:** If the user already named a brand slug (e.g. `magic_spoon`, `hike_footwear`), use it. Otherwise call `list_brands` and ask the user to pick. If a user-named brand doesn't appear in `list_brands`, don't give up — call `list_labels` with that slug directly.

**Hook selection:** Choose the best-fitting liking hook pattern for the brief. If the user provided a specific hook line, use it and map it to the closest pattern. Make your pick, write a one-sentence rationale, and note why you're rejecting the others — you'll need all of this for the final brief output.

**Liking hook patterns:**
- *Real Talk* — "Okay, real talk — I almost didn't post this."
- *Same-Boat* — "If your mornings look like this, we're already friends."
- *Candid Confession* — "I'm the laziest person I know. This is the only thing that stuck."
- *Best-Friend Rec* — "My best friend wouldn't shut up about this. She was right."
- *Self-Roast* — "I ignored this for a year because I'm stubborn. Don't be me."
- *Compliment Open* — "You clearly have good taste — that's exactly why this will annoy you."
- *Inside Joke* — "POV: you swear you'll meal prep this week."
- *Unpolished Review* — "No script, no ring light — here's what I actually think."
- *Shared Enemy* — "We both hate [annoying thing]. So does this brand."
- *Kitchen-Table Chat* — "Come here, sit down — we need to talk about breakfast."

**ActorType preference:** Liking ads live on warm, natural, imperfect footage — authenticity beats polish everywhere in this arc. Confirm with the user:
- **No Actor** — purely product/environment footage
- **Actor B-roll** — hands, partial body, people in motion (recommended)
- **Both** (No Actor + Actor B-roll) — good default
- **No filter** — include all footage

**Brand-fit rationale:** While confirming, form a view on *why liking will work for this specific brand* — does its buyer respond to friend-to-friend energy, and does the brand's voice allow candid, unpolished, similarity-driven creative? You'll write this into the brief's `why.brandFit` field in Step 6 so anyone opening the brief understands the strategy, not just the shot list.

---

## Step 2 — Fetch available labels

Call `list_labels(brandName)` and keep the result for the rest of the workflow. Note:
- **Scene Type**: `Hook`, `Visual Hook`, `CTA`, `Product Benefits`, `Product Shot`, `Lifestyle`, `Bowl Shot`, `Box Shot`, etc.
- **Actor Type**: whether a person appears and whether they are speaking.
- **Product**: maps to specific flavors or SKUs.

---

## Step 3 — Section the brief using the liking narrative arc

Break the brief into **10–14 scenes** using this arc:

| Arc segment | Typical scenes | Purpose |
|---|---|---|
| **Hook** | 1–2 | A disarming, candid, relatable open — the viewer instantly recognizes the vibe and likes the voice. |
| **Relatable Moments** | 2–3 | Everyday scenes the target buyer actually lives — imperfect, warm, familiar. Similarity does the persuading. |
| **Shared Struggle** | 1–2 | The mutual pain or running joke that bonds viewer and voice — the "you too?" beat before the answer. |
| **Product Reveal** | 1–2 | The product enters like a friend's recommendation across the kitchen table — casual, not staged. |
| **Benefit Payoff** | 2–3 | Benefits shown in warm, lived-in contexts — genuine enjoyment, not studio perfection. |
| **Friendship Beat** | 1 | The relationship pays off — comfort, delight, the feeling of a good tip from a good friend. |
| **CTA** | 1 | "Trust me on this one" / "You'll thank me later." |

For each scene capture:
- `name`: short heading (e.g. "Hook — pajama-clad morning kitchen chaos")
- `description`: 1–2 sentences describing what appears on screen
- `arcSegment`: one of the 7 arc segment names above (must match exactly — the HTML uses these for color-coding)

**If the user supplied an explicit scene breakdown, use it. Otherwise show the proposed breakdown and wait for confirmation.**

---

## Step 4 — Build search queries

For each scene, generate **3–5 search queries** — short visual phrases (under ~8 words) describing what is literally on screen, not abstract concepts. Vary phrases to cover different subjects, framings, and environments. You need enough query diversity to surface **4 strong, visually distinct clips per scene** — a single query rarely gets you there.

### Filter rules
- Apply ActorType labels to every query (baseline, not counted toward the category limit).
- Add at most **1 additional label category** per query (Scene Type or Product).
- Use Scene Type matching the arc segment: Hook/Visual Hook for the hook; Lifestyle/Product Benefits for the middle segments; Product Shot for the reveal; CTA for the close.
- Apply Product label only for scenes where the specific SKU is the hero.

---

## Step 5 — Search and collect clip media

**Run all first-round queries in parallel** (all 3–5 queries per scene in one batch). Then fill gaps with follow-up queries only where needed.

For each scene:
1. Call `search_clips_visually` with `brandName`, `query`, and any `filters`.
2. Pool the results from all of the scene's queries and pick the **4 best clips** — rank primarily by lowest `cosineDistance`, but prefer visual variety (different framings, subjects, environments) over four near-identical picks.
3. Deduplicate by `clipSymbol`. Use **at most one clip per `rawVideoPublicId`** — clips sharing a source video look near-identical; keep the best (lowest cosineDistance).
4. If a scene has fewer than 4 strong matches after the first round, run 1–2 follow-up queries with different phrasings before settling for fewer. A scene may ship with 2–3 clips if the library is genuinely thin — never pad with weak matches (cosineDistance well into the "weak" range) just to hit 4.
5. Take `posterUrl` and `previewUrl` directly from the search hit. If a hit is missing `previewUrl` and has a `rawVideoPublicId`, derive it: `https://res.cloudinary.com/recharm/video/upload/so_0,eo_4,q_auto,f_auto/{rawVideoPublicId}.mp4`.
6. Track per clip: `clipSymbol`, `clipName`, `posterUrl`, `previewUrl`, `cosineDistance`, `searchString`, `filters`. `searchString` must be the **exact query string** used in the `search_clips_visually` call that surfaced the clip — the template uses it to build the "Find similar" link, which reopens the full visual-search result set (including the clips you considered but rejected). The template also builds each "View clip" link from `clipSymbol`, so `clipSymbol` must be exactly as returned.
7. Scenes with no strong matches → `clips: []` (renders as "custom shoot needed" gap in the HTML).

**Arc-specific search guidance:**
- **Hook:** Warm, candid, imperfect moments — messy kitchens, pajamas, real-morning energy, natural light.
- **Relatable Moments:** Daily-life footage the buyer recognizes as their own — commute rush, snooze button, fridge stare.
- **Shared Struggle:** Comic-relatable friction — burnt toast, empty cereal box, sad desk breakfast — played warm, not miserable.
- **Product Reveal / Benefit / CTA:** Product Shot, Benefits, CTA Scene Types; favor cozy, natural, unstaged-feeling clips over polished studio shots.

---

## Step 6 — Assemble the JSON data payload

Build this object — the HTML template renders everything from it:

```json
{
  "title": "<e.g. 'You'll Thank Me Later · Magic Spoon · Frosted'>",
  "brand": "<brandName slug>",
  "generatedAt": "<YYYY-MM-DD>",
  "filterChips": [
    { "category": "Actor Type", "value": "Actor B-Roll" },
    { "category": "Actor Type", "value": "No Actor" },
    { "category": "Product", "value": "Frosted" },
    { "category": "Scenes", "value": "12" }
  ],
  "why": {
    "explainer": "<2–3 sentences: what a liking ad is and the mechanism that makes it convert — we say yes to people we like — similarity, candor, and warmth make the recommendation feel like it comes from a friend. Written for someone who has never heard the term.>",
    "brandFit": "<2–3 sentences: why this mechanism fits THIS brand specifically — its category, how its buyers decide, and the context that makes the liking angle credible.>"
  },
  "hook": {
    "pattern": "<Pattern name, e.g. 'Best-Friend Rec'>",
    "line": "<The actual hook line, e.g. 'My best friend wouldn't shut up about this cereal. She was right.'>",
    "rationale": "<1–2 sentences: why this hook fits this brand and audience>"
  },
  "rejectedHooks": [
    {
      "pattern": "<Pattern name>",
      "line": "<What the hook line would have been>",
      "reason": "<1 sentence — specific reason this pattern is a weaker fit here>"
    }
  ],
  "actorType": "<e.g. 'Both (Actor B-Roll + No Actor)'>",
  "scenes": [
    {
      "name": "<Scene heading>",
      "arcSegment": "<Exactly one of: Hook | Relatable Moments | Shared Struggle | Product Reveal | Benefit Payoff | Friendship Beat | CTA>",
      "description": "<1–2 sentences of on-screen description>",
      "clips": [
        {
          "clipSymbol": "<symbol>",
          "clipName": "<clipName from search result>",
          "posterUrl": "<posterUrl from the search hit>",
          "previewUrl": "<previewUrl from the search hit, or derived from rawVideoPublicId, or null>",
          "cosineDistance": 0.142,
          "searchString": "<exact query phrase used to find this clip>",
          "filters": { "<category>": ["<label>"] }
        }
      ]
    }
  ]
}
```

Notes:
- `filterChips` is what renders under the title — one chip per applied footage filter. Include every ActorType label applied, any Product/Scene Type filters used broadly, and a `Scenes` count chip. Keep values short (chip-sized) — this replaces the old prose subtitle.
- `why.explainer` and `why.brandFit` render as a prominent "Why this approach" panel — write them for a reader who has never heard of the liking lever and needs to be convinced it fits their brand. Target **4 clip picks per scene** in `clips`.
- Include **at least 5 rejected hooks** in `rejectedHooks` with specific, brand-aware reasons so the user understands the creative logic behind the chosen pattern.

---

## Step 7 — Render and save the brief

1. **Read** `templates/brief.html` (in this skill's directory).
2. **Replace** the exact string `__BRIEF_DATA_JSON__` with the JSON payload (serialized as a single string — no pretty-printing needed, just ensure it is valid JSON). After serializing, replace every `</` with `<\/` in the JSON string — the payload lives inside an inline `<script>` tag, and an unescaped `</` in any text field would terminate the script and break the whole page.
3. **Call the Recharm MCP `save_html_file` tool** with:
   - `brandName`: the brand slug used throughout this workflow
   - `html`: the fully rendered HTML string (max 20 MB)

   This uploads the HTML to Recharm's public-share storage and returns a shareable `url`.
4. **Surface the `url`** to the user.
5. Give a short **summary**: custom-shoot gaps, scenes that shipped with fewer than 4 clips, arc segments with thin library coverage, any weak-match clips flagged.

---

## What not to do

- Don't confuse liking with social proof or authority — no review counts, no credentials. The persuasion is affection and similarity; evidence talk breaks the spell.
- Don't over-polish — studio-perfect footage kills relatability. In this arc, warmth and imperfection are features.
- Don't reveal the product before the Shared Struggle — protect the tension arc.
- Don't settle for 1 clip per scene — the brief is a menu, not a lock; editors need 4 options per scene to cut alternates.
- Don't pad to 4 clips with weak matches — 2–3 strong picks beat 4 with a dud.
- Don't drop `posterUrl`/`previewUrl` from search hits — the template needs them for thumbnails and hover previews.
- Don't add download links — raw downloadable video URLs aren't available; "View clip" and "Find similar" open in the Recharm app.
- Don't call `save_brief` — use the Recharm MCP `save_html_file` tool with `brandName` + `html`.
- Don't use label values not returned by `list_labels`.
- Don't over-filter — default to 1 label category per query beyond ActorType.
- Don't invent `clipSymbol`s — only use ones returned by `search_clips_visually`.
- Don't refer to a clip by `clipSymbol` alone — always use `clipName` in user-facing output.
- Don't paraphrase `searchString` — it must be the exact query used, or the visual-search results link in the brief won't reproduce the search.
- Don't call `save_html_file` more than once per brief — each call mints a new URL.
- Don't give up if a brand doesn't appear in `list_brands` — try `list_labels` directly.

Referenced files: 1 — file references are metadata, not package contents.

View saved version →

---
name: problem-aware-ad-brief
description: Build a Recharm footage brief for a PROBLEM-AWARE ad — call out the problem, then sell the fix. Use whenever a brief, script, or storyboard targets people who already know they have a problem but not the solution, or the user mentions "problem aware", mid-funnel, pain-point-led ads, or wants an ad that opens by naming the viewer's frustration directly. Searches the user's Recharm clip library and produces a shareable shot-by-shot brief with clip picks. If the user asks for ad footage but the audience awareness level is unclear, ask whether the audience is unaware, problem-aware, or solution-aware before picking a skill.
---

# Problem-Aware Ad Brief

Turn a creative brief aimed at a **problem-aware market** — people who know they have a problem but don't know your solution — into a shot-by-shot footage brief with concrete clip picks from the user's Recharm library, via the `recharm` MCP server.

A problem-aware ad doesn't need to educate; the viewer already feels the pain. The hook's job is to **name that pain so precisely the viewer thinks "that's me"**, then move fast to the solution. Lingering on diagnosis bores this audience; skipping the problem call-out loses the "that's me" moment. That is why the stage order below is enforced, not suggested.

## The four stages — enforce strictly

Every scene belongs to exactly one stage, and stages appear in this order:

1. **Call out the problem** — open by naming the viewer's known frustration, vividly and specifically (e.g. "khakis that bunch and sag by lunch", "another clump of hair in the brush"). The viewer should feel recognized within 2 seconds.
2. **Introduce solution** — reveal the product as the fix.
3. **Answer objections / questions / increase trust** — proof: testimonials, demos, before/after, credentials, ingredients, durability tests, comparisons.
4. **Where to buy** — CTA: website, store, offer.

Scene budget: 8–14 scenes total (each scene ≈ 2–5 s, one Recharm clip). The problem call-out should be punchy (2–4 scenes); weight the middle toward solution + trust. If the user's brief skips a stage or reorders stages, point out the conflict with the problem-aware framework and ask before proceeding.

## Recharm mechanics (read once, applies throughout)

- Call `list_labels(brandName)` once at the start and keep the result; never invent label values or category names — use the exact strings returned (category names vary by brand: `Scene Type` vs `SceneType`, etc.).
- `search_clips_visually` returns slim hits: `clipSymbol`, `clipName`, `rawVideoPublicId`, `sceneType`, `cosineDistance` (lower = closer), `durationMs`, `categoriesAndLabels` (populated only for top hits). Never fetch poster or sprite images; pick on metadata only. Use only the first page — don't paginate.
- Refer to clips in all user-facing output by `clipName` (`<clipSymbol> - <sceneType>`), never bare `clipSymbol`.
- Call `save_brief` exactly once, after picks are final. The server renders the HTML — never build HTML or clip URLs yourself.
- One video per run. If the brief calls for multiple videos, ask the user whether to run per-video sequentially or pick one.

## Workflow

### Step 0 — Create a granular task list

Before any searching, create a visible task list with one task per stage — "Search Problem call-out scenes", "Search Solution-intro scenes", "Search Trust scenes", "Search Where-to-buy scenes" — plus "Confirm scene breakdown", "Establish primary creator", "Assemble & save brief", and "Explain picks & gaps". Mark each in progress and complete as you go. The searches take a while; granular tasks let the user watch the work happen stage by stage and catch a wrong turn early instead of at the end.

### Step 1 — Confirm the brand

Use the brand slug if the user named one; otherwise call `list_brands` and ask. Never guess between candidates.

### Step 2 — Fetch labels

Call `list_labels(brandName)`. Note which categories exist for: scene type, creator, actor type, product, age/gender, and any problem-specific categories (some brands label problem footage explicitly, e.g. a "Problem Shot" or "Problem Angle" category — these are gold for stage 1).

### Step 3 — Section the brief into the four stages

Break the brief into ordered scenes, each tagged with its stage. For each scene capture a short heading, 1–2 sentences of what's on screen, and the stage. If the user supplied an explicit scene breakdown, map it onto the stages (flagging conflicts); otherwise **show the proposed breakdown grouped by stage and wait for confirmation before searching**. If a transcript/VO is provided, use it to inform what each scene shows, but section independently of transcript timing.

### Step 4 — Establish the primary creator

UGC-style ads fall apart when the on-camera person changes between cuts — viewers read it as an edit, not a story, and trust drops. So pick one **primary creator** and stick with them:

1. If the brief names a creator, match it to a label in the creator category (ask if ambiguous).
2. Otherwise run the Stage 1 (problem call-out) searches first with no creator filter. From the top hits' creator labels, shortlist creators who match the brief's audience (use age/gender labels where present). Run 1–2 quick probe searches filtered by each shortlisted creator against a *later-stage* need (e.g. a testimonial or demo) to check they have coverage across the ad — then commit to the one with the best combined match + coverage.
3. Add the creator filter (e.g. `Creator: ["<primary>"]`) to every scene where a person is on camera. Pure product shots / no-actor b-roll don't need it, but if hands or body appear, still prefer the primary creator.
4. If a creator-filtered search returns nothing usable, retry the same filter with a broader query phrase first; only then drop the filter. Any scene that uses a different creator must say so explicitly in its reasoning and in the final summary ("Scene 5 breaks creator consistency: needed Matt, library only has Tyler for this shot").

Tell the user which creator you chose and why before continuing.

### Step 5 — Build queries per scene

2–4 queries per scene. Each query is a short visual phrase (< ~8 words) describing what is literally on screen — "man tugging at baggy khakis" beats "wardrobe frustration". Vary subject/framing/environment across queries. Filters: 0–3 categories, 1–2 labels each.

- **Scene-type filter:** map the stage to the closest scene-type labels in the label list (Problem call-out → problem/hook labels, plus any dedicated problem categories found in Step 2; Introduce solution → product intro/solution labels; Trust → testimonial/demo/before-after/durability labels; Where to buy → CTA/website labels). Use multiple labels in the category to broaden (OR within a category).
- **Actor-type filter (transcript rule):** if a transcript/VO was provided AND an actor-type category exists, add the b-roll/no-actor labels as a hard filter on every query (a VO will be laid over the footage, so on-camera speech would clash). Omit if the category doesn't exist.
- **Product filter:** if a product was named, match it to a product-category label (ask if unsure which). Product filters belong on stage 2–4 scenes; stage 1 should show the *problem*, which often means competitor products or the product worn/used badly — not hero product footage.
- Don't over-filter: AND across categories shrinks results fast. Creator + scene type is usually enough.

### Step 6 — Search and pick, stage by stage

Work through stages in order, updating the task list. Per scene: run each query once, take the 1–2 best hits per query by `cosineDistance`, dedupe by `clipSymbol` (attribute to the best-scoring query), keep at most one clip per `rawVideoPublicId` within a scene, and aim for 3–6 picks. Track per pick the query phrase and filters used — both go into the brief package.

**Be aggressive about declaring gaps.** A wrong clip is worse than no clip: it costs the editor a download-and-reject cycle and hides a real library gap the brand should fill with a shoot. Apply this bar:

- A pick must *literally show* what the scene requires. If a hit's `sceneType` or labels contradict the scene (a CTA clip offered for a problem scene), reject it regardless of distance.
- Treat a best distance that is much worse than your other scenes' results as a red flag, not a least-bad winner.
- If nothing passes, leave the scene's `clips` empty — it renders as a "custom shoot needed" gap. That is a *good* outcome: it tells the brand exactly what to shoot. Never pad with weak matches, and never include a clip you'd have to caveat with "sort of".
- Expect gaps. Problem call-out footage (the product failing, the frustration moment) is exactly what brands rarely shoot. A brief with zero gaps usually means the bar was too low.

### Step 7 — Assemble and save

Build the v2 package — `title`, ordered `scenes` (`name` prefixed with its stage, e.g. "Problem — khakis sagging by lunch", `description`, `clips` with `clipSymbol`/`searchString`/`filters`; empty `clips` for gaps) — and call `save_brief(brandName, {version: "v2", ...})` once. Surface the returned `url`. If the call fails, report it and show the package.

### Step 8 — Explain your work

Your reasoning is part of the deliverable. After saving, give the user:

- **Per scene, 1–2 lines:** stage, the winning query, why the top pick won (distance rank, matching labels, creator), and anything notable you rejected and why.
- **Creator-consistency report:** the primary creator, which scenes hold the line, which break it and why.
- **Gap report:** every "custom shoot needed" scene with a one-line shoot suggestion.
- **Library observations:** patterns the brand should know (e.g. "plenty of product beauty shots, almost no genuine frustration footage — problem-aware hooks will keep hitting this wall").

Keep in-progress narration brief — a line at each stage transition — and put the substance in this final summary.

## What not to do

- Don't open with the product — stage 1 sells recognition of the problem, not the fix.
- Don't add diagnosis/education scenes — this audience already knows the problem; that's the unaware-market skill's job.
- Don't fetch poster/sprite images, paginate searches, invent label values or `clipSymbol`s, or call `save_brief` more than once.
- Don't pad thin scenes with weak matches — declare the gap.
- Don't switch creators silently between scenes.
- Don't ask the user to run searches — you do it via the MCP.

View saved version →

---
name: "reciprocity-ad-brief"
description: >
  Build a Recharm footage brief for a RECIPROCITY ad — give the viewer real value up front (a tip, a hack, a demo, an act of generosity), then let the product pitch land as a fair return of the favor. Use whenever a user provides a brief, concept, or ad idea framed around giving first: free value, 'steal my routine', money-saving tricks, samples, gifts, or generous no-strings openers. Searches the user's Recharm clip library and produces a shareable shot-by-shot brief with clip picks. Trigger on "reciprocity", "give first", "free value", "value-first ad", "steal my routine", "here's a free tip", "give before the ask", or any creative where the ad delivers something useful before selling. Also use when the user wants a soft-sell ad that earns the CTA through generosity rather than pressure.
---

# Reciprocity Ad Brief

You build a Recharm footage brief for a **reciprocity** ad — one that gives the viewer real value up front — a tip, a hack, a demo, an unexpected act of generosity — so the ask at the end feels like a natural return of the favor.

The psychological engine: people feel a deep pull to return favors. When an ad genuinely gives first — useful advice, a working demo, a gift — the viewer incurs a small, pleasant debt, and the product pitch lands as fair exchange rather than interruption. This is distinct from a herd-psychology ad (crowd-driven) or a scarcity ad (urgency-driven): the driver here is *indebtedness born of generosity* — the ad must actually deliver value before it asks.

The Recharm MCP server (`recharm`) is available in this plugin. Key behavioral notes:

- Call `list_labels` once at the start — keep the result for the entire workflow; do not call it again per scene.
- Search hits from `search_clips_visually` already include `posterUrl` and `previewUrl` — use them directly. Only call `get_clip_poster_image` as a fallback if a hit is missing `posterUrl`.
- The template builds "View clip" and "Find similar" links itself from `clipSymbol`, `brand`, and `searchString` — you don't construct any Recharm app URLs.
- Do not paginate `search_clips_visually` — use the first page only.
- Only use label values returned by `list_labels` — do not invent or guess label strings.
- Do **NOT** call `save_brief`. Instead, render the brief using `templates/brief.html` and upload via `save_html_file`.

**Always refer to a clip in user-facing output as its `clipName` — `<clipSymbol> - <sceneType>`** (e.g. "AB - Product Reveal"). If `sceneType` is null, fall back to just the `clipSymbol`.

Follow the steps below in order.

---

## Step 1 — Confirm the brand, hook, and content constraints

**Brand:** If the user already named a brand slug (e.g. `magic_spoon`, `hike_footwear`), use it. Otherwise call `list_brands` and ask the user to pick. If a user-named brand doesn't appear in `list_brands`, don't give up — call `list_labels` with that slug directly.

**Hook selection:** Choose the best-fitting reciprocity hook pattern for the brief. If the user provided a specific hook line, use it and map it to the closest pattern. Make your pick, write a one-sentence rationale, and note why you're rejecting the others — you'll need all of this for the final brief output.

**Reciprocity hook patterns:**
- *Free Blueprint* — "Steal my exact [routine/recipe/system] — no purchase required."
- *Money Saver* — "I'm about to save you $[X] in 30 seconds."
- *No-Strings Tip* — "You don't have to buy anything — just try this one thing."
- *Insider Giveaway* — "The [industry] trick brands don't give away for free."
- *Over-Deliver Promise* — "Screenshot this — it's the only [guide] you'll ever need."
- *Gift Frame* — "Consider this my gift to your [morning routine]."
- *Try-Before-Anything* — "Test this at home before you spend a dime."
- *Reverse Pitch* — "I'm not here to sell you — I'm here to fix your [problem]."
- *Sample Drop* — "We're basically giving this away — here's why."
- *Value Stack* — "Three free fixes for [problem] — the third is the game-changer."

**ActorType preference:** Reciprocity ads live on hands-on, demonstrative footage — the gift must be visibly delivered. Confirm with the user:
- **No Actor** — purely product/environment footage
- **Actor B-roll** — hands, partial body, people in motion (recommended)
- **Both** (No Actor + Actor B-roll) — good default
- **No filter** — include all footage

**Brand-fit rationale:** While confirming, form a view on *why reciprocity will work for this specific brand* — does it have genuinely useful know-how, demos, samples, or generous offers that make the gift feel real (a brand with nothing to teach or give makes a hollow reciprocity ad)? You'll write this into the brief's `why.brandFit` field in Step 6 so anyone opening the brief understands the strategy, not just the shot list.

---

## Step 2 — Fetch available labels

Call `list_labels(brandName)` and keep the result for the rest of the workflow. Note:
- **Scene Type**: `Hook`, `Visual Hook`, `CTA`, `Product Benefits`, `Product Shot`, `Lifestyle`, `Bowl Shot`, `Box Shot`, etc.
- **Actor Type**: whether a person appears and whether they are speaking.
- **Product**: maps to specific flavors or SKUs.

---

## Step 3 — Section the brief using the reciprocity narrative arc

Break the brief into **10–14 scenes** using this arc:

| Arc segment | Typical scenes | Purpose |
|---|---|---|
| **Hook** | 1–2 | Promise immediate, free value. The viewer leans in because there's nothing to buy yet. |
| **Free Value** | 2–3 | Actually deliver the gift — the tip, hack, or demo works on screen before any product branding appears. |
| **Generosity Beat** | 1–2 | Over-deliver: an unexpected extra, sample, or bonus that deepens the sense of a favor received. |
| **Product Reveal** | 1–2 | The product appears as the source of the value just given — not a pivot, a reveal of where the gift came from. |
| **Benefit Payoff** | 2–3 | Show what the product does beyond the free tip — key features, results, reactions. |
| **Fair Exchange** | 1 | Frame the ask as returning the favor — someone happily 'closing the loop' with the product in their life. |
| **CTA** | 1 | A soft, reciprocal ask — "grab yours", often paired with a discount or free gift that extends the generosity. |

For each scene capture:
- `name`: short heading (e.g. "Hook — hands demonstrating the free trick")
- `description`: 1–2 sentences describing what appears on screen
- `arcSegment`: one of the 7 arc segment names above (must match exactly — the HTML uses these for color-coding)

**If the user supplied an explicit scene breakdown, use it. Otherwise show the proposed breakdown and wait for confirmation.**

---

## Step 4 — Build search queries

For each scene, generate **3–5 search queries** — short visual phrases (under ~8 words) describing what is literally on screen, not abstract concepts. Vary phrases to cover different subjects, framings, and environments. You need enough query diversity to surface **4 strong, visually distinct clips per scene** — a single query rarely gets you there.

### Filter rules
- Apply ActorType labels to every query (baseline, not counted toward the category limit).
- Add at most **1 additional label category** per query (Scene Type or Product).
- Use Scene Type matching the arc segment: Hook/Visual Hook for the hook; Lifestyle/Product Benefits for the middle segments; Product Shot for the reveal; CTA for the close.
- Apply Product label only for scenes where the specific SKU is the hero.

---

## Step 5 — Search and collect clip media

**Run all first-round queries in parallel** (all 3–5 queries per scene in one batch). Then fill gaps with follow-up queries only where needed.

For each scene:
1. Call `search_clips_visually` with `brandName`, `query`, and any `filters`.
2. Pool the results from all of the scene's queries and pick the **4 best clips** — rank primarily by lowest `cosineDistance`, but prefer visual variety (different framings, subjects, environments) over four near-identical picks.
3. Deduplicate by `clipSymbol`. Use **at most one clip per `rawVideoPublicId`** — clips sharing a source video look near-identical; keep the best (lowest cosineDistance).
4. If a scene has fewer than 4 strong matches after the first round, run 1–2 follow-up queries with different phrasings before settling for fewer. A scene may ship with 2–3 clips if the library is genuinely thin — never pad with weak matches (cosineDistance well into the "weak" range) just to hit 4.
5. Take `posterUrl` and `previewUrl` directly from the search hit. If a hit is missing `previewUrl` and has a `rawVideoPublicId`, derive it: `https://res.cloudinary.com/recharm/video/upload/so_0,eo_4,q_auto,f_auto/{rawVideoPublicId}.mp4`.
6. Track per clip: `clipSymbol`, `clipName`, `posterUrl`, `previewUrl`, `cosineDistance`, `searchString`, `filters`. `searchString` must be the **exact query string** used in the `search_clips_visually` call that surfaced the clip — the template uses it to build the "Find similar" link, which reopens the full visual-search result set (including the clips you considered but rejected). The template also builds each "View clip" link from `clipSymbol`, so `clipSymbol` must be exactly as returned.
7. Scenes with no strong matches → `clips: []` (renders as "custom shoot needed" gap in the HTML).

**Arc-specific search guidance:**
- **Hook:** Hands mid-demonstration, notebooks, phone screenshots, everyday prep moments — visuals that read "useful, not salesy."
- **Free Value:** Step-by-step hands-on footage — pouring, measuring, assembling, before/after moments that make the tip feel real.
- **Generosity Beat:** Gifting gestures, unboxing, sample handovers, pleasant-surprise reactions, close-ups of "the extra."
- **Product Reveal / Benefit / CTA:** Product Shot, Benefits, CTA Scene Types.

---

## Step 6 — Assemble the JSON data payload

Build this object — the HTML template renders everything from it:

```json
{
  "title": "<e.g. 'Steal My Morning Routine · Magic Spoon · Frosted'>",
  "brand": "<brandName slug>",
  "generatedAt": "<YYYY-MM-DD>",
  "filterChips": [
    { "category": "Actor Type", "value": "Actor B-Roll" },
    { "category": "Actor Type", "value": "No Actor" },
    { "category": "Product", "value": "Frosted" },
    { "category": "Scenes", "value": "12" }
  ],
  "why": {
    "explainer": "<2–3 sentences: what a reciprocity ad is and the mechanism that makes it convert — give first, create a gentle sense of owing, and let the CTA land as fair exchange. Written for someone who has never heard the term.>",
    "brandFit": "<2–3 sentences: why this mechanism fits THIS brand specifically — its category, how its buyers decide, and the context that makes the reciprocity angle credible.>"
  },
  "hook": {
    "pattern": "<Pattern name, e.g. 'Free Blueprint'>",
    "line": "<The actual hook line, e.g. 'Steal my exact 7am routine — no purchase required.'>",
    "rationale": "<1–2 sentences: why this hook fits this brand and audience>"
  },
  "rejectedHooks": [
    {
      "pattern": "<Pattern name>",
      "line": "<What the hook line would have been>",
      "reason": "<1 sentence — specific reason this pattern is a weaker fit here>"
    }
  ],
  "actorType": "<e.g. 'Both (Actor B-Roll + No Actor)'>",
  "scenes": [
    {
      "name": "<Scene heading>",
      "arcSegment": "<Exactly one of: Hook | Free Value | Generosity Beat | Product Reveal | Benefit Payoff | Fair Exchange | CTA>",
      "description": "<1–2 sentences of on-screen description>",
      "clips": [
        {
          "clipSymbol": "<symbol>",
          "clipName": "<clipName from search result>",
          "posterUrl": "<posterUrl from the search hit>",
          "previewUrl": "<previewUrl from the search hit, or derived from rawVideoPublicId, or null>",
          "cosineDistance": 0.142,
          "searchString": "<exact query phrase used to find this clip>",
          "filters": { "<category>": ["<label>"] }
        }
      ]
    }
  ]
}
```

Notes:
- `filterChips` is what renders under the title — one chip per applied footage filter. Include every ActorType label applied, any Product/Scene Type filters used broadly, and a `Scenes` count chip. Keep values short (chip-sized) — this replaces the old prose subtitle.
- `why.explainer` and `why.brandFit` render as a prominent "Why this approach" panel — write them for a reader who has never heard of the reciprocity lever and needs to be convinced it fits their brand. Target **4 clip picks per scene** in `clips`.
- Include **at least 5 rejected hooks** in `rejectedHooks` with specific, brand-aware reasons so the user understands the creative logic behind the chosen pattern.

---

## Step 7 — Render and save the brief

1. **Read** `templates/brief.html` (in this skill's directory).
2. **Replace** the exact string `__BRIEF_DATA_JSON__` with the JSON payload (serialized as a single string — no pretty-printing needed, just ensure it is valid JSON). After serializing, replace every `</` with `<\/` in the JSON string — the payload lives inside an inline `<script>` tag, and an unescaped `</` in any text field would terminate the script and break the whole page.
3. **Call the Recharm MCP `save_html_file` tool** with:
   - `brandName`: the brand slug used throughout this workflow
   - `html`: the fully rendered HTML string (max 20 MB)

   This uploads the HTML to Recharm's public-share storage and returns a shareable `url`.
4. **Surface the `url`** to the user.
5. Give a short **summary**: custom-shoot gaps, scenes that shipped with fewer than 4 clips, arc segments with thin library coverage, any weak-match clips flagged.

---

## What not to do

- Don't confuse this with a discount ad — the gift is *value delivered inside the ad itself*, not just a promo code. If the ad asks before it gives, it isn't reciprocity.
- Don't let the free value be thin or fake — the tip must be complete and usable on its own, or the debt never forms.
- Don't reveal the product before the Generosity Beat — protect the tension arc.
- Don't settle for 1 clip per scene — the brief is a menu, not a lock; editors need 4 options per scene to cut alternates.
- Don't pad to 4 clips with weak matches — 2–3 strong picks beat 4 with a dud.
- Don't drop `posterUrl`/`previewUrl` from search hits — the template needs them for thumbnails and hover previews.
- Don't add download links — raw downloadable video URLs aren't available; "View clip" and "Find similar" open in the Recharm app.
- Don't call `save_brief` — use the Recharm MCP `save_html_file` tool with `brandName` + `html`.
- Don't use label values not returned by `list_labels`.
- Don't over-filter — default to 1 label category per query beyond ActorType.
- Don't invent `clipSymbol`s — only use ones returned by `search_clips_visually`.
- Don't refer to a clip by `clipSymbol` alone — always use `clipName` in user-facing output.
- Don't paraphrase `searchString` — it must be the exact query used, or the visual-search results link in the brief won't reproduce the search.
- Don't call `save_html_file` more than once per brief — each call mints a new URL.
- Don't give up if a brand doesn't appear in `list_brands` — try `list_labels` directly.

Referenced files: 1 — file references are metadata, not package contents.

View saved version →

---
name: "scarcity-ad-brief"
description: >
  Build a Recharm footage brief for a SCARCITY ad — built on limited supply, limited time, or exclusivity: what's rare is wanted, and what's about to run out gets bought now. Use whenever a user provides a brief, concept, or ad idea framed around sell-outs, low stock, countdowns, limited drops, waitlists, seasonal windows, or last-chance urgency. Searches the user's Recharm clip library and produces a shareable shot-by-shot brief with clip picks. Trigger on "scarcity", "limited edition", "selling out", "almost gone", "last chance", "48 hours", "restock", "limited drop", "waitlist", "while supplies last", or any creative where the tension is dwindling availability. Distinct from herd psychology: herd sells 'everyone has it'; scarcity sells 'soon nobody can get it.'
---

# Scarcity Ad Brief

You build a Recharm footage brief for a **scarcity** ad — one built on limited supply, limited time, or exclusivity — what's rare is wanted, and what's about to run out gets bought now instead of later.

The psychological engine: people want more of what they can have less of, and potential loss looms roughly twice as large as equivalent gain. Limited drops, low stock, and closing windows convert "maybe later" into "now." Distinct from herd psychology: herd sells "everyone has it"; scarcity sells "soon nobody can get it." Critical constraint: only use scarcity claims the brand can substantiate — fake urgency destroys trust.

The Recharm MCP server (`recharm`) is available in this plugin. Key behavioral notes:

- Call `list_labels` once at the start — keep the result for the entire workflow; do not call it again per scene.
- Search hits from `search_clips_visually` already include `posterUrl` and `previewUrl` — use them directly. Only call `get_clip_poster_image` as a fallback if a hit is missing `posterUrl`.
- The template builds "View clip" and "Find similar" links itself from `clipSymbol`, `brand`, and `searchString` — you don't construct any Recharm app URLs.
- Do not paginate `search_clips_visually` — use the first page only.
- Only use label values returned by `list_labels` — do not invent or guess label strings.
- Do **NOT** call `save_brief`. Instead, render the brief using `templates/brief.html` and upload via `save_html_file`.

**Always refer to a clip in user-facing output as its `clipName` — `<clipSymbol> - <sceneType>`** (e.g. "AB - Product Reveal"). If `sceneType` is null, fall back to just the `clipSymbol`.

Follow the steps below in order.

---

## Step 1 — Confirm the brand, hook, and content constraints

**Brand:** If the user already named a brand slug (e.g. `magic_spoon`, `hike_footwear`), use it. Otherwise call `list_brands` and ask the user to pick. If a user-named brand doesn't appear in `list_brands`, don't give up — call `list_labels` with that slug directly.

**Hook selection:** Choose the best-fitting scarcity hook pattern for the brief. If the user provided a specific hook line, use it and map it to the closest pattern. Make your pick, write a one-sentence rationale, and note why you're rejecting the others — you'll need all of this for the final brief output.

**Scarcity hook patterns:**
- *Sell-Out Streak* — "This has sold out four times. It's back — for now."
- *Countdown Open* — "You have 48 hours. Then it's gone."
- *Low-Stock Alert* — "There are fewer than [500] of these left."
- *Limited Drop* — "They only make this once a year."
- *Waitlist Flex* — "[30,000] people were on the waitlist. Doors just opened."
- *Last-Chance Frame* — "If you've been waiting for a sign, this is the last one."
- *Exclusive Access* — "Not on shelves. Not on Amazon. Only here."
- *Season Closer* — "When the [seasonal flavor] is gone, it's gone until next year."
- *Price-Window* — "The price goes up Friday. That's not a tactic — that's the calendar."
- *Almost-Missed-It* — "I nearly missed the restock. Don't make my mistake."

**ActorType preference:** Scarcity ads need kinetic, urgent footage — quick hands, last-one moments, demand made visible. Confirm with the user:
- **No Actor** — purely product/environment footage
- **Actor B-roll** — hands, partial body, people in motion (recommended)
- **Both** (No Actor + Actor B-roll) — good default
- **No filter** — include all footage

**Brand-fit rationale:** While confirming, form a view on *why scarcity will work for this specific brand* — does it have real scarcity to point to (genuine sell-outs, limited runs, seasonal SKUs, actual deadlines) that makes the urgency credible? You'll write this into the brief's `why.brandFit` field in Step 6 so anyone opening the brief understands the strategy, not just the shot list.

---

## Step 2 — Fetch available labels

Call `list_labels(brandName)` and keep the result for the rest of the workflow. Note:
- **Scene Type**: `Hook`, `Visual Hook`, `CTA`, `Product Benefits`, `Product Shot`, `Lifestyle`, `Bowl Shot`, `Box Shot`, etc.
- **Actor Type**: whether a person appears and whether they are speaking.
- **Product**: maps to specific flavors or SKUs.

---

## Step 3 — Section the brief using the scarcity narrative arc

Break the brief into **10–14 scenes** using this arc:

| Arc segment | Typical scenes | Purpose |
|---|---|---|
| **Hook** | 1–2 | The scarcity alert — stock, clock, or exclusivity, stated plainly and credibly. |
| **Demand Surge** | 2–3 | Why it runs out — people loving it, flying-off-shelves energy, demand made visible. |
| **Ticking Clock** | 1–2 | Tighten the window — countdown feel, near-miss moments, urgency close-ups. The cost of waiting becomes real. |
| **Product Reveal** | 1–2 | The rare thing itself — hero-lit, desirable, worth the urgency. |
| **Benefit Payoff** | 2–3 | What owners get that latecomers won't — the benefits that justify acting now. |
| **Secure The Win** | 1 | The relief and satisfaction of having gotten one in time — loss averted. |
| **CTA** | 1 | "Get yours before it's gone" / "Claim yours now." |

For each scene capture:
- `name`: short heading (e.g. "Hook — last box grabbed off the shelf")
- `description`: 1–2 sentences describing what appears on screen
- `arcSegment`: one of the 7 arc segment names above (must match exactly — the HTML uses these for color-coding)

**If the user supplied an explicit scene breakdown, use it. Otherwise show the proposed breakdown and wait for confirmation.**

---

## Step 4 — Build search queries

For each scene, generate **3–5 search queries** — short visual phrases (under ~8 words) describing what is literally on screen, not abstract concepts. Vary phrases to cover different subjects, framings, and environments. You need enough query diversity to surface **4 strong, visually distinct clips per scene** — a single query rarely gets you there.

### Filter rules
- Apply ActorType labels to every query (baseline, not counted toward the category limit).
- Add at most **1 additional label category** per query (Scene Type or Product).
- Use Scene Type matching the arc segment: Hook/Visual Hook for the hook; Lifestyle/Product Benefits for the middle segments; Product Shot for the reveal; CTA for the close.
- Apply Product label only for scenes where the specific SKU is the hero.

---

## Step 5 — Search and collect clip media

**Run all first-round queries in parallel** (all 3–5 queries per scene in one batch). Then fill gaps with follow-up queries only where needed.

For each scene:
1. Call `search_clips_visually` with `brandName`, `query`, and any `filters`.
2. Pool the results from all of the scene's queries and pick the **4 best clips** — rank primarily by lowest `cosineDistance`, but prefer visual variety (different framings, subjects, environments) over four near-identical picks.
3. Deduplicate by `clipSymbol`. Use **at most one clip per `rawVideoPublicId`** — clips sharing a source video look near-identical; keep the best (lowest cosineDistance).
4. If a scene has fewer than 4 strong matches after the first round, run 1–2 follow-up queries with different phrasings before settling for fewer. A scene may ship with 2–3 clips if the library is genuinely thin — never pad with weak matches (cosineDistance well into the "weak" range) just to hit 4.
5. Take `posterUrl` and `previewUrl` directly from the search hit. If a hit is missing `previewUrl` and has a `rawVideoPublicId`, derive it: `https://res.cloudinary.com/recharm/video/upload/so_0,eo_4,q_auto,f_auto/{rawVideoPublicId}.mp4`.
6. Track per clip: `clipSymbol`, `clipName`, `posterUrl`, `previewUrl`, `cosineDistance`, `searchString`, `filters`. `searchString` must be the **exact query string** used in the `search_clips_visually` call that surfaced the clip — the template uses it to build the "Find similar" link, which reopens the full visual-search result set (including the clips you considered but rejected). The template also builds each "View clip" link from `clipSymbol`, so `clipSymbol` must be exactly as returned.
7. Scenes with no strong matches → `clips: []` (renders as "custom shoot needed" gap in the HTML).

**Arc-specific search guidance:**
- **Hook:** Empty-shelf moments, last-item shots, package close-ups, checking-phone urgency beats.
- **Demand Surge:** High-energy consumption footage — enthusiastic eating, grabbing, fast-paced lifestyle clips that read "in demand."
- **Ticking Clock:** Clocks, quick hands, near-miss gestures, tight close-ups with kinetic framing.
- **Product Reveal / Benefit / CTA:** Product Shot, Benefits, CTA Scene Types; favor hero-lit, covetable product framing.

---

## Step 6 — Assemble the JSON data payload

Build this object — the HTML template renders everything from it:

```json
{
  "title": "<e.g. 'Back In Stock — For Now · Magic Spoon · Frosted'>",
  "brand": "<brandName slug>",
  "generatedAt": "<YYYY-MM-DD>",
  "filterChips": [
    { "category": "Actor Type", "value": "Actor B-Roll" },
    { "category": "Actor Type", "value": "No Actor" },
    { "category": "Product", "value": "Frosted" },
    { "category": "Scenes", "value": "12" }
  ],
  "why": {
    "explainer": "<2–3 sentences: what a scarcity ad is and the mechanism that makes it convert — rarity raises desire and looming loss converts hesitation into action, since losses weigh about twice as much as gains. Written for someone who has never heard the term.>",
    "brandFit": "<2–3 sentences: why this mechanism fits THIS brand specifically — its category, how its buyers decide, and the context that makes the scarcity angle credible.>"
  },
  "hook": {
    "pattern": "<Pattern name, e.g. 'Sell-Out Streak'>",
    "line": "<The actual hook line, e.g. 'This cereal has sold out four times. It's back — for now.'>",
    "rationale": "<1–2 sentences: why this hook fits this brand and audience>"
  },
  "rejectedHooks": [
    {
      "pattern": "<Pattern name>",
      "line": "<What the hook line would have been>",
      "reason": "<1 sentence — specific reason this pattern is a weaker fit here>"
    }
  ],
  "actorType": "<e.g. 'Both (Actor B-Roll + No Actor)'>",
  "scenes": [
    {
      "name": "<Scene heading>",
      "arcSegment": "<Exactly one of: Hook | Demand Surge | Ticking Clock | Product Reveal | Benefit Payoff | Secure The Win | CTA>",
      "description": "<1–2 sentences of on-screen description>",
      "clips": [
        {
          "clipSymbol": "<symbol>",
          "clipName": "<clipName from search result>",
          "posterUrl": "<posterUrl from the search hit>",
          "previewUrl": "<previewUrl from the search hit, or derived from rawVideoPublicId, or null>",
          "cosineDistance": 0.142,
          "searchString": "<exact query phrase used to find this clip>",
          "filters": { "<category>": ["<label>"] }
        }
      ]
    }
  ]
}
```

Notes:
- `filterChips` is what renders under the title — one chip per applied footage filter. Include every ActorType label applied, any Product/Scene Type filters used broadly, and a `Scenes` count chip. Keep values short (chip-sized) — this replaces the old prose subtitle.
- `why.explainer` and `why.brandFit` render as a prominent "Why this approach" panel — write them for a reader who has never heard of the scarcity lever and needs to be convinced it fits their brand. Target **4 clip picks per scene** in `clips`.
- Include **at least 5 rejected hooks** in `rejectedHooks` with specific, brand-aware reasons so the user understands the creative logic behind the chosen pattern.

---

## Step 7 — Render and save the brief

1. **Read** `templates/brief.html` (in this skill's directory).
2. **Replace** the exact string `__BRIEF_DATA_JSON__` with the JSON payload (serialized as a single string — no pretty-printing needed, just ensure it is valid JSON). After serializing, replace every `</` with `<\/` in the JSON string — the payload lives inside an inline `<script>` tag, and an unescaped `</` in any text field would terminate the script and break the whole page.
3. **Call the Recharm MCP `save_html_file` tool** with:
   - `brandName`: the brand slug used throughout this workflow
   - `html`: the fully rendered HTML string (max 20 MB)

   This uploads the HTML to Recharm's public-share storage and returns a shareable `url`.
4. **Surface the `url`** to the user.
5. Give a short **summary**: custom-shoot gaps, scenes that shipped with fewer than 4 clips, arc segments with thin library coverage, any weak-match clips flagged.

---

## What not to do

- Don't fabricate scarcity — only claims the brand can substantiate: real stock limits, real deadlines, real sell-out history. Fake countdowns destroy trust and can be a legal liability.
- Don't confuse this with herd psychology — herd sells "everyone has it" (FOMO of exclusion); scarcity sells "soon nobody can get it" (loss of availability). If the hook is about the crowd, use herd-psychology-brief.
- Don't reveal the product before the Ticking Clock — protect the tension arc.
- Don't settle for 1 clip per scene — the brief is a menu, not a lock; editors need 4 options per scene to cut alternates.
- Don't pad to 4 clips with weak matches — 2–3 strong picks beat 4 with a dud.
- Don't drop `posterUrl`/`previewUrl` from search hits — the template needs them for thumbnails and hover previews.
- Don't add download links — raw downloadable video URLs aren't available; "View clip" and "Find similar" open in the Recharm app.
- Don't call `save_brief` — use the Recharm MCP `save_html_file` tool with `brandName` + `html`.
- Don't use label values not returned by `list_labels`.
- Don't over-filter — default to 1 label category per query beyond ActorType.
- Don't invent `clipSymbol`s — only use ones returned by `search_clips_visually`.
- Don't refer to a clip by `clipSymbol` alone — always use `clipName` in user-facing output.
- Don't paraphrase `searchString` — it must be the exact query used, or the visual-search results link in the brief won't reproduce the search.
- Don't call `save_html_file` more than once per brief — each call mints a new URL.
- Don't give up if a brand doesn't appear in `list_brands` — try `list_labels` directly.

Referenced files: 1 — file references are metadata, not package contents.

View saved version →

---
name: "social-proof-ad-brief"
description: >
  Build a Recharm footage brief for a SOCIAL PROOF ad — lead with hard evidence of other people's approval: review counts, star ratings, testimonials, UGC, sold-out stats, third-party awards. Use whenever a user provides a brief, concept, or ad idea framed around reviews, ratings, testimonials, 'thousands of customers', before/after results from real users, or evidence-led persuasion. Searches the user's Recharm clip library and produces a shareable shot-by-shot brief with clip picks. Trigger on "social proof", "reviews ad", "testimonial ad", "five-star", "rated #1", "customers say", "as seen in", or any creative where the sell is verifiable evidence that many others approve. NOTE: if the angle is FOMO/bandwagon feeling ("why is everyone switching?"), use herd-psychology-brief instead — this skill is for evidence-led proof, not crowd momentum.
---

# Social Proof Ad Brief

You build a Recharm footage brief for a **social proof** ad — one that leads with hard evidence of other people's approval — review counts, star ratings, testimonials, UGC, sold-out stats — until the viewer concludes "this many people can't be wrong."

The psychological engine: when people are uncertain, they look at what others have decided. This skill is evidence-led: ratings, review excerpts, user counts, real-customer results, stacked until skepticism collapses. It is deliberately distinct from the herd-psychology brief, which sells the *feeling* of a bandwagon and FOMO — here the sell is *verifiable proof*. Herd says "everyone's doing it"; social proof says "here's the evidence."

The Recharm MCP server (`recharm`) is available in this plugin. Key behavioral notes:

- Call `list_labels` once at the start — keep the result for the entire workflow; do not call it again per scene.
- Search hits from `search_clips_visually` already include `posterUrl` and `previewUrl` — use them directly. Only call `get_clip_poster_image` as a fallback if a hit is missing `posterUrl`.
- The template builds "View clip" and "Find similar" links itself from `clipSymbol`, `brand`, and `searchString` — you don't construct any Recharm app URLs.
- Do not paginate `search_clips_visually` — use the first page only.
- Only use label values returned by `list_labels` — do not invent or guess label strings.
- Do **NOT** call `save_brief`. Instead, render the brief using `templates/brief.html` and upload via `save_html_file`.

**Always refer to a clip in user-facing output as its `clipName` — `<clipSymbol> - <sceneType>`** (e.g. "AB - Product Reveal"). If `sceneType` is null, fall back to just the `clipSymbol`.

Follow the steps below in order.

---

## Step 1 — Confirm the brand, hook, and content constraints

**Brand:** If the user already named a brand slug (e.g. `magic_spoon`, `hike_footwear`), use it. Otherwise call `list_brands` and ask the user to pick. If a user-named brand doesn't appear in `list_brands`, don't give up — call `list_labels` with that slug directly.

**Hook selection:** Choose the best-fitting social proof hook pattern for the brief. If the user provided a specific hook line, use it and map it to the closest pattern. Make your pick, write a one-sentence rationale, and note why you're rejecting the others — you'll need all of this for the final brief output.

**Social Proof hook patterns:**
- *Review Mountain* — "12,000 five-star reviews later, I finally tried it."
- *Skeptic Convert* — "I read the reviews to prove it was a scam. I ordered two."
- *Stat Lead* — "9 out of 10 people who try [X] reorder it."
- *Review Digest* — "I read 500 reviews of [X] so you don't have to."
- *Rated #1* — "The internet's highest-rated [category], actually tested."
- *Testimonial Splice* — "Real customers, unscripted, on why they switched."
- *Sold-Out Proof* — "It sold out four times last year. Here's why."
- *Before/After Wall* — "These results came from customers, not the brand."
- *Comment Section* — "The comment section made me buy this."
- *Third-Party Seal* — "[Publication] called it "the best [category] of the year.""

**ActorType preference:** Social proof ads need footage that feels like many different real customers — variety of people, hands, and homes matters more than polish. Confirm with the user:
- **No Actor** — purely product/environment footage
- **Actor B-roll** — hands, partial body, people in motion (recommended)
- **Both** (No Actor + Actor B-roll) — good default
- **No filter** — include all footage

**Brand-fit rationale:** While confirming, form a view on *why social proof will work for this specific brand* — what proof does it actually have (review volume, ratings, press, user counts, results) and is it strong enough to carry an evidence-led ad? You'll write this into the brief's `why.brandFit` field in Step 6 so anyone opening the brief understands the strategy, not just the shot list.

---

## Step 2 — Fetch available labels

Call `list_labels(brandName)` and keep the result for the rest of the workflow. Note:
- **Scene Type**: `Hook`, `Visual Hook`, `CTA`, `Product Benefits`, `Product Shot`, `Lifestyle`, `Bowl Shot`, `Box Shot`, etc.
- **Actor Type**: whether a person appears and whether they are speaking.
- **Product**: maps to specific flavors or SKUs.

---

## Step 3 — Section the brief using the social proof narrative arc

Break the brief into **10–14 scenes** using this arc:

| Arc segment | Typical scenes | Purpose |
|---|---|---|
| **Hook** | 1–2 | Open with the single most striking piece of proof — a number, a rating, a claim that stops the scroll. |
| **Evidence Stack** | 2–3 | Layer the proof: UGC-style clips, review-overlay moments, star ratings, user counts. Volume and variety of evidence. |
| **Skeptic Bridge** | 1–2 | Acknowledge doubt — "I thought it was hype too" — then tip it with one more proof point. Doubt voiced is doubt disarmed. |
| **Product Reveal** | 1–2 | The product all that evidence points to, clearly on screen. |
| **Benefit Payoff** | 2–3 | Show the product earning those reviews — the specific features customers praise most. |
| **Verdict** | 1 | The viewer's conclusion made visual — a satisfied user, a five-star moment, the reorder. |
| **CTA** | 1 | "See why thousands switched" / "Read the reviews yourself." |

For each scene capture:
- `name`: short heading (e.g. "Hook — scrolling five-star reviews on phone")
- `description`: 1–2 sentences describing what appears on screen
- `arcSegment`: one of the 7 arc segment names above (must match exactly — the HTML uses these for color-coding)

**If the user supplied an explicit scene breakdown, use it. Otherwise show the proposed breakdown and wait for confirmation.**

---

## Step 4 — Build search queries

For each scene, generate **3–5 search queries** — short visual phrases (under ~8 words) describing what is literally on screen, not abstract concepts. Vary phrases to cover different subjects, framings, and environments. You need enough query diversity to surface **4 strong, visually distinct clips per scene** — a single query rarely gets you there.

### Filter rules
- Apply ActorType labels to every query (baseline, not counted toward the category limit).
- Add at most **1 additional label category** per query (Scene Type or Product).
- Use Scene Type matching the arc segment: Hook/Visual Hook for the hook; Lifestyle/Product Benefits for the middle segments; Product Shot for the reveal; CTA for the close.
- Apply Product label only for scenes where the specific SKU is the hero.

---

## Step 5 — Search and collect clip media

**Run all first-round queries in parallel** (all 3–5 queries per scene in one batch). Then fill gaps with follow-up queries only where needed.

For each scene:
1. Call `search_clips_visually` with `brandName`, `query`, and any `filters`.
2. Pool the results from all of the scene's queries and pick the **4 best clips** — rank primarily by lowest `cosineDistance`, but prefer visual variety (different framings, subjects, environments) over four near-identical picks.
3. Deduplicate by `clipSymbol`. Use **at most one clip per `rawVideoPublicId`** — clips sharing a source video look near-identical; keep the best (lowest cosineDistance).
4. If a scene has fewer than 4 strong matches after the first round, run 1–2 follow-up queries with different phrasings before settling for fewer. A scene may ship with 2–3 clips if the library is genuinely thin — never pad with weak matches (cosineDistance well into the "weak" range) just to hit 4.
5. Take `posterUrl` and `previewUrl` directly from the search hit. If a hit is missing `previewUrl` and has a `rawVideoPublicId`, derive it: `https://res.cloudinary.com/recharm/video/upload/so_0,eo_4,q_auto,f_auto/{rawVideoPublicId}.mp4`.
6. Track per clip: `clipSymbol`, `clipName`, `posterUrl`, `previewUrl`, `cosineDistance`, `searchString`, `filters`. `searchString` must be the **exact query string** used in the `search_clips_visually` call that surfaced the clip — the template uses it to build the "Find similar" link, which reopens the full visual-search result set (including the clips you considered but rejected). The template also builds each "View clip" link from `clipSymbol`, so `clipSymbol` must be exactly as returned.
7. Scenes with no strong matches → `clips: []` (renders as "custom shoot needed" gap in the HTML).

**Arc-specific search guidance:**
- **Hook:** Phone-in-hand reading moments, surprised reactions, scrolling reviews — visuals that pair with a bold proof stat overlay.
- **Evidence Stack:** UGC-feeling footage — casual home settings, multiple different people/hands using the product, authentic unpolished moments.
- **Skeptic Bridge:** Skeptical inspection close-ups — reading labels, turning the box over, raised-eyebrow beats before conversion.
- **Product Reveal / Benefit / CTA:** Product Shot, Benefits, CTA Scene Types; favor clips showing the praised feature in action.

---

## Step 6 — Assemble the JSON data payload

Build this object — the HTML template renders everything from it:

```json
{
  "title": "<e.g. '12,000 Five-Star Mornings · Magic Spoon · Frosted'>",
  "brand": "<brandName slug>",
  "generatedAt": "<YYYY-MM-DD>",
  "filterChips": [
    { "category": "Actor Type", "value": "Actor B-Roll" },
    { "category": "Actor Type", "value": "No Actor" },
    { "category": "Product", "value": "Frosted" },
    { "category": "Scenes", "value": "12" }
  ],
  "why": {
    "explainer": "<2–3 sentences: what a social proof ad is and the mechanism that makes it convert — uncertain buyers copy the verified decisions of others, and stacked evidence collapses skepticism. Written for someone who has never heard the term.>",
    "brandFit": "<2–3 sentences: why this mechanism fits THIS brand specifically — its category, how its buyers decide, and the context that makes the social proof angle credible.>"
  },
  "hook": {
    "pattern": "<Pattern name, e.g. 'Skeptic Convert'>",
    "line": "<The actual hook line, e.g. 'I read the reviews to prove it was a scam. I ordered two.'>",
    "rationale": "<1–2 sentences: why this hook fits this brand and audience>"
  },
  "rejectedHooks": [
    {
      "pattern": "<Pattern name>",
      "line": "<What the hook line would have been>",
      "reason": "<1 sentence — specific reason this pattern is a weaker fit here>"
    }
  ],
  "actorType": "<e.g. 'Both (Actor B-Roll + No Actor)'>",
  "scenes": [
    {
      "name": "<Scene heading>",
      "arcSegment": "<Exactly one of: Hook | Evidence Stack | Skeptic Bridge | Product Reveal | Benefit Payoff | Verdict | CTA>",
      "description": "<1–2 sentences of on-screen description>",
      "clips": [
        {
          "clipSymbol": "<symbol>",
          "clipName": "<clipName from search result>",
          "posterUrl": "<posterUrl from the search hit>",
          "previewUrl": "<previewUrl from the search hit, or derived from rawVideoPublicId, or null>",
          "cosineDistance": 0.142,
          "searchString": "<exact query phrase used to find this clip>",
          "filters": { "<category>": ["<label>"] }
        }
      ]
    }
  ]
}
```

Notes:
- `filterChips` is what renders under the title — one chip per applied footage filter. Include every ActorType label applied, any Product/Scene Type filters used broadly, and a `Scenes` count chip. Keep values short (chip-sized) — this replaces the old prose subtitle.
- `why.explainer` and `why.brandFit` render as a prominent "Why this approach" panel — write them for a reader who has never heard of the social proof lever and needs to be convinced it fits their brand. Target **4 clip picks per scene** in `clips`.
- Include **at least 5 rejected hooks** in `rejectedHooks` with specific, brand-aware reasons so the user understands the creative logic behind the chosen pattern.

---

## Step 7 — Render and save the brief

1. **Read** `templates/brief.html` (in this skill's directory).
2. **Replace** the exact string `__BRIEF_DATA_JSON__` with the JSON payload (serialized as a single string — no pretty-printing needed, just ensure it is valid JSON). After serializing, replace every `</` with `<\/` in the JSON string — the payload lives inside an inline `<script>` tag, and an unescaped `</` in any text field would terminate the script and break the whole page.
3. **Call the Recharm MCP `save_html_file` tool** with:
   - `brandName`: the brand slug used throughout this workflow
   - `html`: the fully rendered HTML string (max 20 MB)

   This uploads the HTML to Recharm's public-share storage and returns a shareable `url`.
4. **Surface the `url`** to the user.
5. Give a short **summary**: custom-shoot gaps, scenes that shipped with fewer than 4 clips, arc segments with thin library coverage, any weak-match clips flagged.

---

## What not to do

- Don't drift into herd-psychology territory — that skill sells FOMO and bandwagon *feeling*; this one sells verifiable *evidence*. If the core line is "why is everyone…", switch to herd-psychology-brief.
- Don't invent proof — only cite review counts, ratings, and press the brand can substantiate. Fabricated evidence is a legal and trust liability.
- Don't reveal the product before the Skeptic Bridge — protect the tension arc.
- Don't settle for 1 clip per scene — the brief is a menu, not a lock; editors need 4 options per scene to cut alternates.
- Don't pad to 4 clips with weak matches — 2–3 strong picks beat 4 with a dud.
- Don't drop `posterUrl`/`previewUrl` from search hits — the template needs them for thumbnails and hover previews.
- Don't add download links — raw downloadable video URLs aren't available; "View clip" and "Find similar" open in the Recharm app.
- Don't call `save_brief` — use the Recharm MCP `save_html_file` tool with `brandName` + `html`.
- Don't use label values not returned by `list_labels`.
- Don't over-filter — default to 1 label category per query beyond ActorType.
- Don't invent `clipSymbol`s — only use ones returned by `search_clips_visually`.
- Don't refer to a clip by `clipSymbol` alone — always use `clipName` in user-facing output.
- Don't paraphrase `searchString` — it must be the exact query used, or the visual-search results link in the brief won't reproduce the search.
- Don't call `save_html_file` more than once per brief — each call mints a new URL.
- Don't give up if a brand doesn't appear in `list_brands` — try `list_labels` directly.

Referenced files: 1 — file references are metadata, not package contents.

View saved version →

---
name: solution-aware-ad-brief
description: Build a Recharm footage brief for a SOLUTION-AWARE ad — lead with the product, win on proof and differentiation. Use whenever a brief, script, or storyboard targets people who already know solutions like this exist (bottom-of-funnel, retargeting, comparison shoppers), or the user mentions "solution aware", "warm audience", "why us", competitor comparisons, or wants an ad that opens on the product itself. Searches the user's Recharm clip library and produces a shareable shot-by-shot brief with clip picks. If the user asks for ad footage but the audience awareness level is unclear, ask whether the audience is unaware, problem-aware, or solution-aware before picking a skill.
---

# Solution-Aware Ad Brief

Turn a creative brief aimed at a **solution-aware market** — people who already know products like this exist and are weighing options — into a shot-by-shot footage brief with concrete clip picks from the user's Recharm library, via the `recharm` MCP server.

A solution-aware ad has nothing to teach and no pain to dramatize: the viewer is comparing. Lead with the product immediately, then win the comparison with **proof and differentiation** — that middle stage is where this ad lives or dies. Re-explaining the problem wastes the viewer's patience. That is why the stage order below is enforced, not suggested.

## The three stages — enforce strictly

Every scene belongs to exactly one stage, and stages appear in this order:

1. **Call out the solution** — open on the product, named and shown, with its sharpest differentiating claim (e.g. "the only khakis with 4-way stretch", "the dermatologist-built hair serum"). No problem setup.
2. **Answer objections / questions / increase trust** — the heart of the ad: testimonials, demos, before/after, credentials, ingredients, durability tests, competitor comparisons, social proof. Anticipate the specific doubts a comparison shopper has (does it work? why this one? is it worth more?) and give each its own scene.
3. **Where to buy** — CTA: website, store, offer, guarantee.

Scene budget: 6–12 scenes total (each scene ≈ 2–5 s, one Recharm clip). Stage 1 should be 1–3 scenes; weight heavily toward stage 2 — proof is the product here. If the user's brief skips a stage or reorders stages, point out the conflict with the solution-aware framework and ask before proceeding.

## Recharm mechanics (read once, applies throughout)

- Call `list_labels(brandName)` once at the start and keep the result; never invent label values or category names — use the exact strings returned (category names vary by brand: `Scene Type` vs `SceneType`, etc.).
- `search_clips_visually` returns slim hits: `clipSymbol`, `clipName`, `rawVideoPublicId`, `sceneType`, `cosineDistance` (lower = closer), `durationMs`, `categoriesAndLabels` (populated only for top hits). Never fetch poster or sprite images; pick on metadata only. Use only the first page — don't paginate.
- Refer to clips in all user-facing output by `clipName` (`<clipSymbol> - <sceneType>`), never bare `clipSymbol`.
- Call `save_brief` exactly once, after picks are final. The server renders the HTML — never build HTML or clip URLs yourself.
- One video per run. If the brief calls for multiple videos, ask the user whether to run per-video sequentially or pick one.

## Workflow

### Step 0 — Create a granular task list

Before any searching, create a visible task list with one task per stage — "Search Solution call-out scenes", "Search Trust & differentiation scenes", "Search Where-to-buy scenes" — plus "Confirm scene breakdown", "Establish primary creator", "Assemble & save brief", and "Explain picks & gaps". Because stage 2 carries most of the ad, split it into one task per objection/proof theme (e.g. "Search demo proof", "Search testimonial proof", "Search comparison proof"). Mark each in progress and complete as you go — granular tasks let the user watch the work happen and catch a wrong turn early instead of at the end.

### Step 1 — Confirm the brand

Use the brand slug if the user named one; otherwise call `list_brands` and ask. Never guess between candidates.

### Step 2 — Fetch labels

Call `list_labels(brandName)`. Note which categories exist for: scene type, creator, actor type, product, age/gender, and any proof-friendly labels (testimonial, demo, before/after, durability, competitors, features/benefits categories — these map directly to stage 2 scenes).

### Step 3 — Section the brief into the three stages

Break the brief into ordered scenes, each tagged with its stage. For each stage-2 scene, also note *which objection it answers* — that's the scene's job. If the user supplied an explicit scene breakdown, map it onto the stages (flagging conflicts); otherwise **show the proposed breakdown grouped by stage and wait for confirmation before searching**. If a transcript/VO is provided, use it to inform what each scene shows, but section independently of transcript timing.

### Step 4 — Establish the primary creator

UGC-style ads fall apart when the on-camera person changes between cuts — viewers read it as an edit, not a story, and trust drops. Comparison shoppers are the most skeptical audience of all, so consistency matters most here. Pick one **primary creator** and stick with them:

1. If the brief names a creator, match it to a label in the creator category (ask if ambiguous).
2. Otherwise run the Stage 1 (solution call-out) searches first with no creator filter. From the top hits' creator labels, shortlist creators who match the brief's audience (use age/gender labels where present). Run 1–2 quick probe searches filtered by each shortlisted creator against a *stage-2* need (e.g. a testimonial or demo) to check they have coverage across the ad — then commit to the one with the best combined match + coverage.
3. Add the creator filter (e.g. `Creator: ["<primary>"]`) to every scene where a person is on camera. Pure product shots / no-actor b-roll don't need it, but if hands or body appear, still prefer the primary creator. Exception: a montage of *multiple different* testimonial voices can be a deliberate social-proof choice — if the brief implies one, confirm with the user, then treat each testimonial scene's creator variety as intentional and say so in the reasoning.
4. If a creator-filtered search returns nothing usable, retry the same filter with a broader query phrase first; only then drop the filter. Any scene that uses a different creator must say so explicitly in its reasoning and in the final summary.

Tell the user which creator you chose and why before continuing.

### Step 5 — Build queries per scene

2–4 queries per scene. Each query is a short visual phrase (< ~8 words) describing what is literally on screen — "close-up serum dropper on scalp" beats "product efficacy". Vary subject/framing/environment across queries. Filters: 0–3 categories, 1–2 labels each.

- **Scene-type filter:** map the stage to the closest scene-type labels in the label list (Solution call-out → product intro/product shot/holding product labels; Trust → testimonial/demo/before-after/durability/competitors labels, matched to the objection each scene answers; Where to buy → CTA/website labels). Use multiple labels in the category to broaden (OR within a category).
- **Actor-type filter (transcript rule):** if a transcript/VO was provided AND an actor-type category exists, add the b-roll/no-actor labels as a hard filter on every query (a VO will be laid over the footage, so on-camera speech would clash). Omit if the category doesn't exist.
- **Product filter:** if a product was named, match it to a product-category label (ask if unsure which) and apply it broadly — in a solution-aware ad nearly every scene is product-relevant, and showing the *wrong* product to a comparison shopper is a credibility hit.
- Don't over-filter: AND across categories shrinks results fast. Creator + scene type, or product + scene type, is usually enough.

### Step 6 — Search and pick, stage by stage

Work through stages in order, updating the task list. Per scene: run each query once, take the 1–2 best hits per query by `cosineDistance`, dedupe by `clipSymbol` (attribute to the best-scoring query), keep at most one clip per `rawVideoPublicId` within a scene, and aim for 3–6 picks. Track per pick the query phrase and filters used — both go into the brief package.

**Be aggressive about declaring gaps.** A wrong clip is worse than no clip: it costs the editor a download-and-reject cycle and hides a real library gap the brand should fill with a shoot. Apply this bar:

- A pick must *literally show* what the scene requires — including the *right product*. A hit showing a different product than the brief's is a rejection, regardless of distance.
- If a hit's `sceneType` or labels contradict the scene (a hook clip offered for a demo scene), reject it.
- Treat a best distance that is much worse than your other scenes' results as a red flag, not a least-bad winner.
- If nothing passes, leave the scene's `clips` empty — it renders as a "custom shoot needed" gap. That is a *good* outcome: it tells the brand exactly what to shoot. Never pad with weak matches, and never include a clip you'd have to caveat with "sort of".
- Expect gaps. Specific proof footage (comparisons, before/after for a named product) is often missing. A brief with zero gaps usually means the bar was too low.

### Step 7 — Assemble and save

Build the v2 package — `title`, ordered `scenes` (`name` prefixed with its stage and, for stage 2, the objection it answers, e.g. "Trust (does it actually work?) — before/after hairline", `description`, `clips` with `clipSymbol`/`searchString`/`filters`; empty `clips` for gaps) — and call `save_brief(brandName, {version: "v2", ...})` once. Surface the returned `url`. If the call fails, report it and show the package.

### Step 8 — Explain your work

Your reasoning is part of the deliverable. After saving, give the user:

- **Per scene, 1–2 lines:** stage (and the objection answered, for stage 2), the winning query, why the top pick won (distance rank, matching labels, creator, correct product), and anything notable you rejected and why.
- **Creator-consistency report:** the primary creator, which scenes hold the line, which break it and why (including any deliberate testimonial-montage variety).
- **Gap report:** every "custom shoot needed" scene with a one-line shoot suggestion.
- **Library observations:** patterns the brand should know (e.g. "no competitor-comparison footage at all — differentiation scenes will always need custom shoots").

Keep in-progress narration brief — a line at each stage transition — and put the substance in this final summary.

## What not to do

- Don't open with problem setup or education — this audience is past it; those are the problem-aware and unaware skills' jobs.
- Don't let stage 2 collapse into generic product beauty shots — every trust scene must answer a specific objection.
- Don't fetch poster/sprite images, paginate searches, invent label values or `clipSymbol`s, or call `save_brief` more than once.
- Don't pad thin scenes with weak matches — declare the gap.
- Don't switch creators silently between scenes.
- Don't ask the user to run searches — you do it via the MCP.

View saved version →

---
name: "uber-ad-brief"
description: >
  Build a Recharm footage brief for an Uber-style ad — where the creative concept is set inside
  a rideshare and centers on the driver-passenger dynamic as the vehicle for storytelling about
  a product. Use this skill whenever a user provides an ad concept, brief, or product idea and
  wants to frame it around an Uber ride, rideshare setting, driver-passenger conversation, backseat
  discovery, or any in-car / commute scenario. Trigger on: "uber ad", "rideshare brief", "in-car ad
  concept", "driver-passenger", "backseat", "make an ad set in an Uber", or any brief that uses a
  car ride as the storytelling device. Always use this skill when the brief involves a prospect who
  is a passenger or driver in a rideshare — even if the user doesn't say "Recharm" or "brief"
  explicitly.
---

# Uber-Style Ad Brief Creator

You turn a product and an ad concept direction into a fully sectioned Uber-style creative brief,
then search the user's Recharm clip library for footage that fits, and produce a shareable brief.

The Recharm MCP server (`recharm`) is available. Key rules:

- Call `list_labels` **once** at the start — reuse it throughout, never call it again per scene.
- Do NOT build HTML. Hand `save_brief` a structured v2 package; the server renders everything.
- Call `save_brief` exactly **once**, after all clip picks are final.
- Do not paginate `search_clips_visually` — use the first page only.
- Only use label values returned by `list_labels` — never invent or guess label strings.
- Always refer to a clip as its `clipName`: `<clipSymbol> - <sceneType>`. Fall back to `clipSymbol`
  if `sceneType` is null.

---

## Uber Ad Concept Archetypes

When the user's brief implies an approach, map it to one (or a blend) of these archetypes. If the
brief is open-ended, present 3–4 options and let the user pick.

### Original 10 Archetypes

1. **Expert Advice POV** — Driver stops mid-ride to offer niche, unsolicited life advice about the
   product. Feels like a genuine slightly-intrusive Uber conversation.
2. **Hidden Compartment Reveal** — Driver reveals the car is secretly stocked with the brand's
   products instead of the usual water/chargers. Acts like it's the most normal thing in the world.
3. **Music Taste Test** — Driver plays a track that perfectly matches the product's vibe, using the
   car's speakers to demonstrate the product's benefits (sound quality, mood-setting, etc.).
4. **"Wait, Look at This" Detour** — Driver pulls over at a scenic spot or store specifically to
   show the passenger a cool product feature or use case. Breaks the monotony of the car shot.
5. **Passenger Challenge** — Driver challenges the passenger to try the product for the duration of
   the ride and captures their raw, unfiltered first-impression reaction.
6. **Backseat Vlogger** — Dashcam-style angle catches the passenger "accidentally" discovering the
   product in the backseat and starting an organic conversation about it.
7. **Road Trip Prep** — Montage of the driver prepping the car — and prominently including the
   product as an essential part of the service they offer every passenger.
8. **Inside Joke Dynamic** — Driver and passenger are already laughing together, then effortlessly
   pivot to how the product solved a common problem they both share.
9. **Before/After Traffic Jam** — High-stress, gridlocked ride transforms into a relaxed experience
   once the driver introduces the product. Positions it as a mood-shifter or stress-reliever.
10. **The Rating Play** — Driver jokingly asks for a "5-star rating," but only if the passenger
    agrees that [Product] is the best thing they've tried all day. Familiar mechanic → CTA.

### 10 Additional Archetypes

11. **ETA Countdown** — Driver references the ride's remaining time ("6 minutes left") and shows
    how the product fits perfectly into any commute window — making every ride feel productive.
12. **Surge Pricing Confession** — Driver jokes about surge pricing, then pivots: "But some things
    are always worth the premium," pivoting to the product's value proposition.
13. **Lost and Found** — Driver pulls out the product: "Someone left this last week — I tried it,
    now I keep it for every ride." Stranger's social proof in a highly believable setting.
14. **Late Night Shift** — Midnight or early-AM ride; driver reveals the product that keeps them
    going through long shifts. Authentic tiredness + genuine product discovery.
15. **Airport Goodbye** — Frantic airport drop-off, driver hands the product to the passenger as a
    parting gift: "You're going to need this." High-emotion, memorable ending.
16. **Carpool Chemistry** — Two strangers sharing a rideshare bond over the product during an
    otherwise awkward shared ride. Turns a mundane moment into a connection.
17. **Parallel Lives Split-Screen** — Driver and passenger are shown using the product in their
    separate daily lives, connected only by the ride. Universality of the product.
18. **Turn-by-Turn Tutorial** — Driver gives a GPS-navigation-style walkthrough of the product:
    "In 200 feet, open the app…" Playful format, clear product education.
19. **Long Haul Confession** — Extended airport or cross-city ride; driver opens up about how the
    product genuinely changed something in their life. Intimacy of a long shared journey.
20. **Wrong Turn, Right Product** — GPS reroute or wrong turn accidentally leads to discovering the
    product. Reframes the "mistake" as serendipity. Works well for discovery-stage brands.

---

## Step 1 — Confirm brand, archetype, and actor preference

**Brand:** If the user named a brand slug, use it. Otherwise call `list_brands` and ask the user to
pick. If the slug isn't in `list_brands`, try `list_labels` with it directly before giving up.

**Archetype:** Map the user's brief to one or a blend of the archetypes above. If it's unclear,
present 3–4 good fits and wait for confirmation. The archetype shapes every scene heading and the
tone of the search queries — getting it right upfront matters.

**Actor Type preference:** Uber-style ads are inherently actor-forward (driver, passenger), so
the default is **No Filter** unless the user's brief specifically calls for B-roll only. Confirm:

- **No Filter** (default) — includes talking heads, UGC, Actor B-roll, and No Actor
- **Actor B-roll only** — partial body, hands, environmental shots only
- **No Actor** — purely product/environment footage (unusual for this format)

---

## Step 2 — Fetch available labels

Call `list_labels(brandName)`. Keep the result for the full workflow. Note:

- **Scene Type**: used to filter for hooks, CTAs, product shots, etc.
- **Actor Type**: confirms available actor/B-roll categories.
- **Product**: maps to specific flavors/SKUs if the brief names one.

---

## Step 3 — Section the brief into Uber-style scenes

Break the brief into ordered scenes. Target **10–14 scenes** (Uber ads are tight — cap at 14).
Each scene ≈ 2–4 seconds. For each scene capture:

- A short heading that names both the Uber context and the product beat
  (e.g., "Backseat Reveal — passenger opens product for first time")
- 1–2 sentences describing exactly what appears on screen
- The narrative role: hook / ride-context-setup / product-discovery / benefit / reaction / CTA

**Uber scene palette — lean on these visual contexts:**

- Car interior: backseat POV, front-passenger POV, rearview mirror framing
- Driver face / driver hands on wheel
- City or highway passing through the window (movement = life)
- Product appearing in the cupholder, center console, seatback pocket, or passenger's hand
- Driver-passenger eye contact via rearview mirror
- Phone screen showing the Uber app (ETA, rating prompt, arrival)
- Arrival / door-open moment (high energy, natural cut point)
- Reaction shots — genuine surprise, delight, or laughter

**Show the proposed scene breakdown to the user and wait for confirmation before proceeding.**

---

## Step 4 — Build search queries

For each scene, generate **2–4 search queries**. Each query:

- A short visual phrase (under ~8 words) describing what's literally on screen.
  Favor phrases that include in-car cues: "woman in backseat opening small box",
  "driver smiling in rearview mirror", "city lights through car window at night".
- An optional `filters` object. Default: at most **1 label category** beyond ActorType.

**Scene Type guidance for Uber briefs:**

- Opening scenes → `Hook` or `Visual Hook`
- Product first-touch / discovery scenes → `Product Shot` or `Product Benefits`
- Reaction / conversation scenes → no Scene Type filter (let the visual query do the work)
- Closing scenes → `CTA`

---

## Step 5 — Search, section by section

**Fire all queries for all scenes in parallel** in the same tool call batch (first round).
Only run follow-ups after reviewing first-round results.

For each scene:

1. Call `search_clips_visually` for each query phrase.
2. Select **1–2 top results per query** by lowest `cosineDistance`.
3. Aim for **3–5 clips per scene** total. Deduplicate by `clipSymbol`.
4. Use **at most one clip per `rawVideoPublicId`** within a scene — clips sharing an ID are
   near-duplicate moments from the same source video. Keep the lowest cosineDistance, drop the rest.
5. Deprioritize clips over 4000 ms when shorter alternatives exist at similar cosineDistance.
6. Track the `query phrase` and `filters` used for each picked clip — both go into the package.
7. If a scene has no strong matches, leave `clips: []` (renders as "custom shoot needed" gap) and
   note it in the final summary.

---

## Step 6 — Assemble the brief package

Build the v2 structured package:

- `title`: short brief title capturing the archetype and product,
  e.g., `"Hidden Compartment Reveal" · Magic Spoon · Cold Traffic`.
- `scenes`: ordered list. Each scene:
  - `name`: the scene heading.
  - `description`: the 1–2 sentence on-screen description.
  - `clips`: picked clips, each with `clipSymbol`, `searchString`, `filters`.
  - Empty `clips: []` for custom-shoot gaps.

Do not provide URLs, durations, or display names — the server derives them from `clipSymbol`.

---

## Step 7 — Save and share

Call `save_brief` exactly once:

```
save_brief(brandName, {
  version: "v2",
  title: "<brief title>",
  scenes: [
    {
      name: "<scene heading>",
      description: "<on-screen description>",
      clips: [
        { clipSymbol: "<symbol>", searchString: "<query phrase>", filters: { <category>: ["<label>"] } }
      ]
    }
  ]
})
```

Surface the returned `url` as the shareable link. Follow with a short **summary**:
scenes needing custom footage, any unusually long clips, and observations about gaps in the library
specifically for in-car / Uber-context footage.

---

## What not to do

- Don't skip the archetype selection step — it's what makes this format distinctive.
- Don't use label values not returned by `list_labels`.
- Don't over-filter: 1 label category per query (beyond ActorType) is the default.
- Don't fetch or examine poster images or sprite images.
- Don't invent `clipSymbol`s — only use ones from `search_clips_visually` results.
- Don't refer to clips by `clipSymbol` alone in user-facing output — always use `clipName`.
- Don't call `save_brief` more than once, and never before clip picks are final.
- Don't build HTML or construct clip URLs yourself.

View saved version →

---
name: unaware-ad-brief
description: Build a Recharm footage brief for an UNAWARE-market ad — symptom-led, educate-then-sell. Use whenever a brief, script, or storyboard targets cold or top-of-funnel audiences, or the user mentions "unaware", "cold traffic", "doesn't know they have a problem", or wants an ad that opens on a symptom or relatable moment rather than the product. Searches the user's Recharm clip library and produces a shareable shot-by-shot brief with clip picks. If the user asks for ad footage but the audience awareness level is unclear, ask whether the audience is unaware, problem-aware, or solution-aware before picking a skill.
---

# Unaware-Market Ad Brief

Turn a creative brief aimed at an **unaware market** — people who don't yet know they have a problem — into a shot-by-shot footage brief with concrete clip picks from the user's Recharm library, via the `recharm` MCP server.

An unaware-market ad must earn the right to sell. It opens on a **symptom** the viewer recognizes from their own life, **diagnoses** the underlying problem, and only then introduces the product. Selling too early loses this audience entirely — that is why the stage order below is enforced, not suggested.

## The five stages — enforce strictly

Every scene belongs to exactly one stage, and stages appear in this order:

1. **Symptom** — open on a relatable, *felt* experience. No product, no problem-naming yet. (e.g. "she keeps finding hair on her pillow", "he tugs at pants that don't fit right".)
2. **Diagnose with problem** — name and explain the underlying problem behind the symptom. Educational and authority footage belongs here (expert talking, animation, close-ups of the cause).
3. **Introduce solution** — reveal the product as the answer to the diagnosed problem.
4. **Answer objections / questions / increase trust** — proof: testimonials, demos, before/after, credentials, ingredients, durability tests.
5. **Where to buy** — CTA: website, store, offer.

Scene budget: 10–18 scenes total (each scene ≈ 2–5 s, one Recharm clip). Weight scenes toward stages 1–2 — the education work is what this ad type does that others skip. If the user's brief skips a stage or reorders stages, point out the conflict with the unaware framework and ask before proceeding.

## Recharm mechanics (read once, applies throughout)

- Call `list_labels(brandName)` once at the start and keep the result; never invent label values or category names — use the exact strings returned (category names vary by brand: `Scene Type` vs `SceneType`, etc.).
- `search_clips_visually` returns slim hits: `clipSymbol`, `clipName`, `rawVideoPublicId`, `sceneType`, `cosineDistance` (lower = closer), `durationMs`, `categoriesAndLabels` (populated only for top hits). Never fetch poster or sprite images; pick on metadata only. Use only the first page — don't paginate.
- Refer to clips in all user-facing output by `clipName` (`<clipSymbol> - <sceneType>`), never bare `clipSymbol`.
- Call `save_brief` exactly once, after picks are final. The server renders the HTML — never build HTML or clip URLs yourself.
- One video per run. If the brief calls for multiple videos, ask the user whether to run per-video sequentially or pick one.

## Workflow

### Step 0 — Create a granular task list

Before any searching, create a visible task list with one task per stage — "Search Symptom scenes", "Search Diagnose scenes", "Search Solution-intro scenes", "Search Trust scenes", "Search Where-to-buy scenes" — plus "Confirm scene breakdown", "Establish primary creator", "Assemble & save brief", and "Explain picks & gaps". Mark each in progress and complete as you go. The searches take a while; granular tasks let the user watch the work happen stage by stage and catch a wrong turn early instead of at the end.

### Step 1 — Confirm the brand

Use the brand slug if the user named one; otherwise call `list_brands` and ask. Never guess between candidates.

### Step 2 — Fetch labels

Call `list_labels(brandName)`. Note which categories exist for: scene type, creator, actor type, product, age/gender. You'll use them below.

### Step 3 — Section the brief into the five stages

Break the brief into ordered scenes, each tagged with its stage. For each scene capture a short heading, 1–2 sentences of what's on screen, and the stage. If the user supplied an explicit scene breakdown, map it onto the stages (flagging conflicts); otherwise **show the proposed breakdown grouped by stage and wait for confirmation before searching**. If a transcript/VO is provided, use it to inform what each scene shows, but section independently of transcript timing.

### Step 4 — Establish the primary creator

UGC-style ads fall apart when the on-camera person changes between cuts — viewers read it as an edit, not a story, and trust drops. So pick one **primary creator** and stick with them:

1. If the brief names a creator, match it to a label in the creator category (ask if ambiguous).
2. Otherwise run the Stage 1 (Symptom) searches first with no creator filter. From the top hits' creator labels, shortlist creators who match the brief's audience (use age/gender labels where present). Run 1–2 quick probe searches filtered by each shortlisted creator against a *later-stage* need (e.g. a testimonial or demo) to check they have coverage across the ad — then commit to the one with the best combined match + coverage.
3. Add the creator filter (e.g. `Creator: ["<primary>"]`) to every scene where a person is on camera. Pure product shots / no-actor b-roll don't need it, but if hands or body appear, still prefer the primary creator.
4. If a creator-filtered search returns nothing usable, retry the same filter with a broader query phrase first; only then drop the filter. Any scene that uses a different creator must say so explicitly in its reasoning and in the final summary ("Scene 7 breaks creator consistency: needed Jill, library only has Lauren for this shot").

Tell the user which creator you chose and why before continuing.

### Step 5 — Build queries per scene

2–4 queries per scene. Each query is a short visual phrase (< ~8 words) describing what is literally on screen — "woman finding hair in shower drain" beats "hair loss anxiety". Vary subject/framing/environment across queries. Filters: 0–3 categories, 1–2 labels each.

- **Scene-type filter:** map the stage to the closest scene-type labels in the label list (Symptom → hook/problem-style labels; Diagnose → problem/educational/authority labels; Introduce solution → product intro/solution labels; Trust → testimonial/demo/before-after labels; Where to buy → CTA/website labels). Use multiple labels in the category to broaden (OR within a category).
- **Actor-type filter (transcript rule):** if a transcript/VO was provided AND an actor-type category exists, add the b-roll/no-actor labels as a hard filter on every query (a VO will be laid over the footage, so on-camera speech would clash). Omit if the category doesn't exist.
- **Product filter:** if a product was named, match it to a product-category label (ask if unsure which). Product filters belong on stage 3–5 scenes; stages 1–2 should normally be product-free — that's the point of this ad type.
- Don't over-filter: AND across categories shrinks results fast. Creator + scene type is usually enough.

### Step 6 — Search and pick, stage by stage

Work through stages in order, updating the task list. Per scene: run each query once, take the 1–2 best hits per query by `cosineDistance`, dedupe by `clipSymbol` (attribute to the best-scoring query), keep at most one clip per `rawVideoPublicId` within a scene, and aim for 3–6 picks. Track per pick the query phrase and filters used — both go into the brief package.

**Be aggressive about declaring gaps.** A wrong clip is worse than no clip: it costs the editor a download-and-reject cycle and hides a real library gap the brand should fill with a shoot. Apply this bar:

- A pick must *literally show* what the scene requires. If a hit's `sceneType` or labels contradict the scene (a CTA clip offered for a symptom scene), reject it regardless of distance.
- Treat a best distance that is much worse than your other scenes' results as a red flag, not a least-bad winner.
- If nothing passes, leave the scene's `clips` empty — it renders as a "custom shoot needed" gap. That is a *good* outcome: it tells the brand exactly what to shoot. Never pad with weak matches, and never include a clip you'd have to caveat with "sort of".
- Expect gaps. Unaware-market ads need symptom and diagnosis footage most libraries are thin on. A brief with zero gaps usually means the bar was too low.

### Step 7 — Assemble and save

Build the v2 package — `title`, ordered `scenes` (`name` prefixed with its stage, e.g. "Symptom — hair on the pillow", `description`, `clips` with `clipSymbol`/`searchString`/`filters`; empty `clips` for gaps) — and call `save_brief(brandName, {version: "v2", ...})` once. Surface the returned `url`. If the call fails, report it and show the package.

### Step 8 — Explain your work

Your reasoning is part of the deliverable. After saving, give the user:

- **Per scene, 1–2 lines:** stage, the winning query, why the top pick won (distance rank, matching labels, creator), and anything notable you rejected and why.
- **Creator-consistency report:** the primary creator, which scenes hold the line, which break it and why.
- **Gap report:** every "custom shoot needed" scene with a one-line shoot suggestion.
- **Library observations:** patterns the brand should know (e.g. "almost no product-free symptom footage — top-of-funnel ads will keep hitting this wall").

Keep in-progress narration brief — a line at each stage transition — and put the substance in this final summary.

## What not to do

- Don't sell before stage 3 — no product in Symptom or Diagnose scenes unless the user insists.
- Don't fetch poster/sprite images, paginate searches, invent label values or `clipSymbol`s, or call `save_brief` more than once.
- Don't pad thin scenes with weak matches — declare the gap.
- Don't switch creators silently between scenes.
- Don't ask the user to run searches — you do it via the MCP.

View saved version →

---
name: "unity-ad-brief"
description: >
  Build a Recharm footage brief for a UNITY ad — built on shared identity: not 'people like you use this' but 'this is ours; we made it for us.' Use whenever a user provides a brief, concept, or ad idea framed around tribe, family, community, subculture, co-creation, 'made by us for us', hometown pride, or in-group belonging. Searches the user's Recharm clip library and produces a shareable shot-by-shot brief with clip picks. Trigger on "unity", "tribe ad", "community ad", "our people", "if you know you know", "IYKYK", "made by runners for runners", "for my fellow", "join the family", or any creative where buying feels like belonging. Distinct from liking (affection between individuals) and social proof (evidence from strangers) — unity is shared membership.
---

# Unity Ad Brief

You build a Recharm footage brief for a **unity** ad — one built on shared identity — not "people like you use this" but "this is ours; we made it for us." Buying feels like belonging, not shopping.

The psychological engine: the deepest Cialdini lever: shared identity. People say yes to "one of us." Family, hometown, subculture, profession, co-creation — when the brand credibly sits inside the viewer's "we," the purchase becomes an act of membership. Distinct from liking (affection and similarity between individuals) and social proof (evidence from strangers): unity is *membership*, and the ad must speak insider fluently or it reads as pandering.

The Recharm MCP server (`recharm`) is available in this plugin. Key behavioral notes:

- Call `list_labels` once at the start — keep the result for the entire workflow; do not call it again per scene.
- Search hits from `search_clips_visually` already include `posterUrl` and `previewUrl` — use them directly. Only call `get_clip_poster_image` as a fallback if a hit is missing `posterUrl`.
- The template builds "View clip" and "Find similar" links itself from `clipSymbol`, `brand`, and `searchString` — you don't construct any Recharm app URLs.
- Do not paginate `search_clips_visually` — use the first page only.
- Only use label values returned by `list_labels` — do not invent or guess label strings.
- Do **NOT** call `save_brief`. Instead, render the brief using `templates/brief.html` and upload via `save_html_file`.

**Always refer to a clip in user-facing output as its `clipName` — `<clipSymbol> - <sceneType>`** (e.g. "AB - Product Reveal"). If `sceneType` is null, fall back to just the `clipSymbol`.

Follow the steps below in order.

---

## Step 1 — Confirm the brand, hook, and content constraints

**Brand:** If the user already named a brand slug (e.g. `magic_spoon`, `hike_footwear`), use it. Otherwise call `list_brands` and ask the user to pick. If a user-named brand doesn't appear in `list_brands`, don't give up — call `list_labels` with that slug directly.

**Hook selection:** Choose the best-fitting unity hook pattern for the brief. If the user provided a specific hook line, use it and map it to the closest pattern. Make your pick, write a one-sentence rationale, and note why you're rejecting the others — you'll need all of this for the final brief output.

**Unity hook patterns:**
- *In-Group Call* — "This is for my fellow [runners/nurses/new parents]."
- *IYKYK* — "If you know, you know."
- *Made-By-Us* — "Made by [runners], for [runners]. Nobody else would get it."
- *We Don't* — "Our people don't do [mainstream compromise]."
- *Family Table* — "In this house, breakfast is sacred."
- *Roots Nod* — "For everyone who grew up on [shared memory] — we fixed it."
- *Tribe Test* — "You can spot one of us from across the gym."
- *Co-Creation* — "You asked. We built it. It's yours too."
- *Insider Language* — "[Niche slang] — if that made sense, this is for you."
- *Belonging Promise* — "You've found your people. Here's the handshake."

**ActorType preference:** Unity ads need footage of people together — groups, families, teams sharing rituals; solo shots undercut the lever. Confirm with the user:
- **No Actor** — purely product/environment footage
- **Actor B-roll** — hands, partial body, people in motion (recommended)
- **Both** (No Actor + Actor B-roll) — good default
- **No filter** — include all footage

**Brand-fit rationale:** While confirming, form a view on *why unity will work for this specific brand* — what "we" can the brand credibly claim (a subculture, lifestyle, family ritual, community it genuinely belongs to), and does it speak that group's language fluently? You'll write this into the brief's `why.brandFit` field in Step 6 so anyone opening the brief understands the strategy, not just the shot list.

---

## Step 2 — Fetch available labels

Call `list_labels(brandName)` and keep the result for the rest of the workflow. Note:
- **Scene Type**: `Hook`, `Visual Hook`, `CTA`, `Product Benefits`, `Product Shot`, `Lifestyle`, `Bowl Shot`, `Box Shot`, etc.
- **Actor Type**: whether a person appears and whether they are speaking.
- **Product**: maps to specific flavors or SKUs.

---

## Step 3 — Section the brief using the unity narrative arc

Break the brief into **10–14 scenes** using this arc:

| Arc segment | Typical scenes | Purpose |
|---|---|---|
| **Hook** | 1–2 | Name the tribe — the viewer feels seen as a member, not targeted as a customer. |
| **Tribe Portrait** | 2–3 | The in-group in its element — rituals, shared spaces, insider moments only members recognize. |
| **Belonging Bridge** | 1–2 | The shared value or memory that makes membership real — the "only we get this" beat. |
| **Product Reveal** | 1–2 | The product as tribe artifact — ours, built for how we actually live. |
| **Benefit Payoff** | 2–3 | Benefits framed through the group's values and standards — what *we* care about, delivered. |
| **We Moment** | 1 | The togetherness payoff — the member thriving among their people, product in hand. |
| **CTA** | 1 | "Join the family" / "Made for us — get yours." |

For each scene capture:
- `name`: short heading (e.g. "Hook — family gathered around the breakfast table")
- `description`: 1–2 sentences describing what appears on screen
- `arcSegment`: one of the 7 arc segment names above (must match exactly — the HTML uses these for color-coding)

**If the user supplied an explicit scene breakdown, use it. Otherwise show the proposed breakdown and wait for confirmation.**

---

## Step 4 — Build search queries

For each scene, generate **3–5 search queries** — short visual phrases (under ~8 words) describing what is literally on screen, not abstract concepts. Vary phrases to cover different subjects, framings, and environments. You need enough query diversity to surface **4 strong, visually distinct clips per scene** — a single query rarely gets you there.

### Filter rules
- Apply ActorType labels to every query (baseline, not counted toward the category limit).
- Add at most **1 additional label category** per query (Scene Type or Product).
- Use Scene Type matching the arc segment: Hook/Visual Hook for the hook; Lifestyle/Product Benefits for the middle segments; Product Shot for the reveal; CTA for the close.
- Apply Product label only for scenes where the specific SKU is the hero.

---

## Step 5 — Search and collect clip media

**Run all first-round queries in parallel** (all 3–5 queries per scene in one batch). Then fill gaps with follow-up queries only where needed.

For each scene:
1. Call `search_clips_visually` with `brandName`, `query`, and any `filters`.
2. Pool the results from all of the scene's queries and pick the **4 best clips** — rank primarily by lowest `cosineDistance`, but prefer visual variety (different framings, subjects, environments) over four near-identical picks.
3. Deduplicate by `clipSymbol`. Use **at most one clip per `rawVideoPublicId`** — clips sharing a source video look near-identical; keep the best (lowest cosineDistance).
4. If a scene has fewer than 4 strong matches after the first round, run 1–2 follow-up queries with different phrasings before settling for fewer. A scene may ship with 2–3 clips if the library is genuinely thin — never pad with weak matches (cosineDistance well into the "weak" range) just to hit 4.
5. Take `posterUrl` and `previewUrl` directly from the search hit. If a hit is missing `previewUrl` and has a `rawVideoPublicId`, derive it: `https://res.cloudinary.com/recharm/video/upload/so_0,eo_4,q_auto,f_auto/{rawVideoPublicId}.mp4`.
6. Track per clip: `clipSymbol`, `clipName`, `posterUrl`, `previewUrl`, `cosineDistance`, `searchString`, `filters`. `searchString` must be the **exact query string** used in the `search_clips_visually` call that surfaced the clip — the template uses it to build the "Find similar" link, which reopens the full visual-search result set (including the clips you considered but rejected). The template also builds each "View clip" link from `clipSymbol`, so `clipSymbol` must be exactly as returned.
7. Scenes with no strong matches → `clips: []` (renders as "custom shoot needed" gap in the HTML).

**Arc-specific search guidance:**
- **Hook:** Group-identity signals — matching gear, team energy, family tables, community spaces.
- **Tribe Portrait:** Ritual footage — group workouts, family breakfasts, shared routines, insider gestures.
- **Belonging Bridge:** Intimate connection beats — knowing glances, hand-offs, shared meals, generational moments.
- **Product Reveal / Benefit / CTA:** Product Shot, Benefits, CTA Scene Types; favor clips where the product appears inside group life, not isolated.

---

## Step 6 — Assemble the JSON data payload

Build this object — the HTML template renders everything from it:

```json
{
  "title": "<e.g. 'Made For Our Mornings · Magic Spoon · Frosted'>",
  "brand": "<brandName slug>",
  "generatedAt": "<YYYY-MM-DD>",
  "filterChips": [
    { "category": "Actor Type", "value": "Actor B-Roll" },
    { "category": "Actor Type", "value": "No Actor" },
    { "category": "Product", "value": "Frosted" },
    { "category": "Scenes", "value": "12" }
  ],
  "why": {
    "explainer": "<2–3 sentences: what a unity ad is and the mechanism that makes it convert — people say yes to "one of us" — shared identity turns buying into an act of belonging. Written for someone who has never heard the term.>",
    "brandFit": "<2–3 sentences: why this mechanism fits THIS brand specifically — its category, how its buyers decide, and the context that makes the unity angle credible.>"
  },
  "hook": {
    "pattern": "<Pattern name, e.g. 'Made-By-Us'>",
    "line": "<The actual hook line, e.g. 'Made by breakfast people, for breakfast people. Nobody else would get it.'>",
    "rationale": "<1–2 sentences: why this hook fits this brand and audience>"
  },
  "rejectedHooks": [
    {
      "pattern": "<Pattern name>",
      "line": "<What the hook line would have been>",
      "reason": "<1 sentence — specific reason this pattern is a weaker fit here>"
    }
  ],
  "actorType": "<e.g. 'Both (Actor B-Roll + No Actor)'>",
  "scenes": [
    {
      "name": "<Scene heading>",
      "arcSegment": "<Exactly one of: Hook | Tribe Portrait | Belonging Bridge | Product Reveal | Benefit Payoff | We Moment | CTA>",
      "description": "<1–2 sentences of on-screen description>",
      "clips": [
        {
          "clipSymbol": "<symbol>",
          "clipName": "<clipName from search result>",
          "posterUrl": "<posterUrl from the search hit>",
          "previewUrl": "<previewUrl from the search hit, or derived from rawVideoPublicId, or null>",
          "cosineDistance": 0.142,
          "searchString": "<exact query phrase used to find this clip>",
          "filters": { "<category>": ["<label>"] }
        }
      ]
    }
  ]
}
```

Notes:
- `filterChips` is what renders under the title — one chip per applied footage filter. Include every ActorType label applied, any Product/Scene Type filters used broadly, and a `Scenes` count chip. Keep values short (chip-sized) — this replaces the old prose subtitle.
- `why.explainer` and `why.brandFit` render as a prominent "Why this approach" panel — write them for a reader who has never heard of the unity lever and needs to be convinced it fits their brand. Target **4 clip picks per scene** in `clips`.
- Include **at least 5 rejected hooks** in `rejectedHooks` with specific, brand-aware reasons so the user understands the creative logic behind the chosen pattern.

---

## Step 7 — Render and save the brief

1. **Read** `templates/brief.html` (in this skill's directory).
2. **Replace** the exact string `__BRIEF_DATA_JSON__` with the JSON payload (serialized as a single string — no pretty-printing needed, just ensure it is valid JSON). After serializing, replace every `</` with `<\/` in the JSON string — the payload lives inside an inline `<script>` tag, and an unescaped `</` in any text field would terminate the script and break the whole page.
3. **Call the Recharm MCP `save_html_file` tool** with:
   - `brandName`: the brand slug used throughout this workflow
   - `html`: the fully rendered HTML string (max 20 MB)

   This uploads the HTML to Recharm's public-share storage and returns a shareable `url`.
4. **Surface the `url`** to the user.
5. Give a short **summary**: custom-shoot gaps, scenes that shipped with fewer than 4 clips, arc segments with thin library coverage, any weak-match clips flagged.

---

## What not to do

- Don't confuse unity with liking or social proof — liking is affection for a person, proof is evidence from strangers; unity is shared membership. If the creative can't credibly claim "we," use liking-ad-brief instead.
- Don't fake insider fluency — get the tribe's language, rituals, and details right or the ad reads as pandering and backfires.
- Don't reveal the product before the Belonging Bridge — protect the tension arc.
- Don't settle for 1 clip per scene — the brief is a menu, not a lock; editors need 4 options per scene to cut alternates.
- Don't pad to 4 clips with weak matches — 2–3 strong picks beat 4 with a dud.
- Don't drop `posterUrl`/`previewUrl` from search hits — the template needs them for thumbnails and hover previews.
- Don't add download links — raw downloadable video URLs aren't available; "View clip" and "Find similar" open in the Recharm app.
- Don't call `save_brief` — use the Recharm MCP `save_html_file` tool with `brandName` + `html`.
- Don't use label values not returned by `list_labels`.
- Don't over-filter — default to 1 label category per query beyond ActorType.
- Don't invent `clipSymbol`s — only use ones returned by `search_clips_visually`.
- Don't refer to a clip by `clipSymbol` alone — always use `clipName` in user-facing output.
- Don't paraphrase `searchString` — it must be the exact query used, or the visual-search results link in the brief won't reproduce the search.
- Don't call `save_html_file` more than once per brief — each call mints a new URL.
- Don't give up if a brand doesn't appear in `list_brands` — try `list_labels` directly.

Referenced files: 1 — file references are metadata, not package contents.