Compare commits

...
6 Commits
Author SHA1 Message Date
Corey Haines 0ba2a7fafc Merge pull request #442 from coreyhaines31/development
release: v2.8.8 — creative review page (ad-creative)
2026-07-12 23:21:28 -07:00
Corey HainesandClaude Fable 5 81270bcd54 feat(ad-creative): shareable creative review page — client approval artifact (2.7.0) (#441)
* feat(ad-creative): shareable creative review page (client approval artifact) (2.7.0)

Self-contained HTML template (assets/creative-review-template.html) that
presents generated concepts as in-feed platform mockups with a frame-by-
frame storyboard, selectable copy variations, and a required grounding
disclosure — the visual upgrade to INDEX.md. Driven entirely by a DATA
object; no build or deps. Full data model + grounding rules in
references/creative-review-page.md. Repo release 2.8.8. Closes #440.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix(ad-creative): harden review-page template per codex review

- P1: DATA moved to inert <script type=application/json> block (values
  can't execute) + documented \u003c escaping rule for the </script>
  breakout; malformed JSON now shows a clear error banner
- P1: platform list whitelisted to instagram/facebook + escaped in
  attr/label (was raw-interpolated)
- platform toggle now renders real FB chrome (link card + text actions)
  vs IG (swipe bar + icon actions) — was visually inert
- broken/missing images fall back to the label+prompt placeholder as
  documented (placeholder base layer + image removes itself on error)
- doc consistency: agency wording, JSON data-model note, VERSIONS trigger list

Verified in-browser: FB/IG toggle, error banner, and HTML-payload escaping.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
2026-07-12 23:21:00 -07:00
Corey Haines 5139746081 Merge pull request #438 from coreyhaines31/development
release: npx skills install docs fix
2026-07-10 16:02:00 -07:00
Corey HainesandClaude Fable 5 09a81edda8 docs: clarify npx skills install dirs per agent (#435)
The CLI no longer unconditionally symlinks into .claude/skills — Claude Code
gets .claude/skills only when selected (interactively or via -a claude-code).
Agent-detected non-interactive runs can land universal-only in .agents/skills,
which Claude Code does not read. Verified empirically against skills CLI 1.5.15
and Claude Code 2.1.173.

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
2026-07-10 16:01:18 -07:00
Corey Haines 52c269e2b3 Merge pull request #437 from coreyhaines31/development
release: v2.8.7 — creative strategy loop + hook system
2026-07-10 14:59:32 -07:00
Corey HainesandClaude Fable 5 003db09cae feat(ad-creative): Mode 4 creative strategy loop + hook system (2.6.0) (#436)
* feat(ad-creative): Mode 4 creative strategy loop + hook system (2.6.0)

The workflow layer for deciding which ads to make: three-signal
synthesis, evidence-ranked concepts, account-state branching, capacity-
checked roadmap with production tiers, monthly retro. Plus a complete
hook system (component trio, generation pipeline, diagnostic funnel,
on-ramp rule, fidelity ladder). customer-research gains the zero-review
persona fallback (2.0.1); marketing-loops gains the monthly-creative-
retro loop (1.2.0). Closes #434.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* chore: release bookkeeping for 2.8.7

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix(ad-creative): address codex review — soften algorithm claims, decouple evidence from production tier, fix CPC direction, remove non-repo skill reference, flexible scaling mix

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix: decouple T2 tier from evidence ranks; clean stale changelog wording

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
2026-07-10 14:59:23 -07:00
13 changed files with 832 additions and 12 deletions
+1 -1
View File
@@ -6,7 +6,7 @@
},
"metadata": {
"description": "Marketing skills for AI agents — conversion optimization, copywriting, SEO, paid ads, and growth",
"version": "2.8.6",
"version": "2.8.8",
"repository": "https://github.com/coreyhaines31/marketingskills"
},
"plugins": [
+1 -1
View File
@@ -1,7 +1,7 @@
{
"name": "marketing-skills",
"description": "Marketing skills for AI agents — conversion optimization, copywriting, SEO, paid ads, ad creative, and growth",
"version": "2.8.6",
"version": "2.8.8",
"author": {
"name": "Corey Haines"
},
+8 -1
View File
@@ -122,7 +122,14 @@ npx skills add coreyhaines31/marketingskills --skill cro copywriting
npx skills add coreyhaines31/marketingskills --list
```
This automatically installs to your `.agents/skills/` directory (and symlinks into `.claude/skills/` for Claude Code compatibility).
The CLI detects which agents you have installed and asks where to install. For Claude Code it installs into `.claude/skills/`; universal agents share `.agents/skills/`.
> [!TIP]
> If you run the command from **inside** an agent session (e.g., asking Claude Code to install the skills for you), the CLI runs non-interactively and may only install to the universal `.agents/skills/` directory, which Claude Code does not read. Pass the agent explicitly:
>
> ```bash
> npx skills add coreyhaines31/marketingskills -a claude-code
> ```
### Option 2: Claude Code Plugin
+13 -3
View File
@@ -5,7 +5,7 @@ Current versions of all skills. Agents can compare against local versions to che
| Skill | Version | Last Updated |
|-------|---------|--------------|
| ab-testing | 2.0.0 | 2026-05-05 |
| ad-creative | 2.5.0 | 2026-07-09 |
| ad-creative | 2.7.0 | 2026-07-12 |
| ai-seo | 2.2.0 | 2026-07-09 |
| analytics | 2.0.0 | 2026-05-05 |
| aso | 2.0.0 | 2026-05-05 |
@@ -19,7 +19,7 @@ Current versions of all skills. Agents can compare against local versions to che
| copy-editing | 2.0.0 | 2026-05-05 |
| copywriting | 2.0.1 | 2026-06-16 |
| cro | 2.0.0 | 2026-05-05 |
| customer-research | 2.0.0 | 2026-05-05 |
| customer-research | 2.0.1 | 2026-07-10 |
| directory-submissions | 2.0.0 | 2026-05-05 |
| emails | 2.0.0 | 2026-05-05 |
| free-tools | 2.0.0 | 2026-05-05 |
@@ -28,7 +28,7 @@ Current versions of all skills. Agents can compare against local versions to che
| lead-magnets | 2.0.0 | 2026-05-05 |
| marketing-council | 1.0.0 | 2026-07-06 |
| marketing-ideas | 2.0.0 | 2026-05-05 |
| marketing-loops | 1.1.0 | 2026-07-05 |
| marketing-loops | 1.2.0 | 2026-07-10 |
| marketing-plan | 1.1.0 | 2026-05-29 |
| marketing-psychology | 2.0.0 | 2026-05-05 |
| offers | 1.0.0 | 2026-06-16 |
@@ -54,6 +54,16 @@ Current versions of all skills. Agents can compare against local versions to che
## Recent Changes
### 2.8.8 (2026-07-12)
- **ad-creative** (2.6.0 → 2.7.0): added the **creative review page** — a shareable, self-contained HTML artifact that presents generated concepts for a client or stakeholder to review and pick (the visual upgrade to `INDEX.md`; pattern reverse-engineered from a real agency creative-approval page, re-expressed originally). New `assets/creative-review-template.html`: one file, inline CSS+JS, no build or dependencies, driven entirely by a `DATA` object — renders concept tabs (each a strategic angle), a pixel-accurate in-feed Instagram/Facebook preview with a whitelist-handle toggle, a labeled frame-by-frame storyboard (tap to jump), selectable headline variations that overlay the preview, primary text, destination/CTA/offer, optional rollout mechanics, and a required grounding disclosure; frames render real images (URL / relative path / data URI) or styled label+prompt placeholders for concepts not yet rendered. New `references/creative-review-page.md`: when to produce one, the full data model, the frame-storyboard-as-carousel-arc link to `carousel-frameworks.md`, the hard grounding rule (every concept discloses what's real; illustrative proof is labeled illustrative — never launder fiction as fact), and how to populate/verify/deliver (open locally, host on any static host, or hand off the file). SKILL.md adds a Creative Review Page output-format section, a Mode 3 pointer, and 'creative review page' + 'present ad creative for approval' triggers. New eval (id 10) covers template use over markdown, narrative-job frame labels, and the grounding disclosure. Browser-verified: concept switching, platform/handle toggles, and frame navigation all render correctly.
### 2.8.7 (2026-07-10)
- **ad-creative** (2.5.0 → 2.6.0): added **Mode 4 — the Creative Strategy Loop**, the upstream workflow layer for deciding which ads are worth making (built so the same capability ships in any agent running the library, incl. Magister; workflow shapes informed by public creative-strategist practice, expressed originally). New `references/creative-roadmap.md`: three-signal synthesis (account performance via the platform CLIs; customer/brand language via the Grounded Inputs corpus + customer-research; external organic via scraping, social listening, and competitor-profiling) on a monthly-deep-dive + weekly-refresh cadence with a receipts rule (no insight enters the icebox without its source); concepts as segment × motivation × angle × format hypotheses ranked on a six-tier evidence scale; **account-state branching** (exploration state: wide net-new mix, per-metric win redefinition, iterate only on hits, four root causes to check; scaling state: winner-variation-heavy mix with visually-distinct variations, sub-angle probes, a standing exploration allocation); the **roadmap artifact** (icebox → quarterly themes → monthly slate with T1 iteration / T2 remix / T3 production tiers and a hard capacity check); per-concept briefs handed to Modes 1–3; and the **monthly creative retro** (winners/losers/metric-wins/learnings/kills, judged at concept level, every learning landing as an icebox update, re-rank, or kill). New `references/hook-system.md`: hooks as three components (visual action / spoken line / caption) with the no-duplication rule; the segment → motivation → format → hook generation pipeline output as a hook matrix; an eight-move opening menu; the **diagnostic funnel** mapping thumbstop/hold/CTR/CVR to which component to fix; the **on-ramp rule** (every hook test is an on-ramp test); fidelity laddering tied to production tiers; and inherited grounding rules plus organic language mining. SKILL.md adds the Mode 4 section and 'creative strategy,' 'creative roadmap,' 'creative retro,' 'hook writing' triggers. New eval (id 9) covers exploration-state diagnosis, evidence-ranked slates, and the receipts rule.
- **customer-research** (2.0.0 → 2.0.1): added the **zero-review persona fallback** to Persona Generation — a four-step proxy ladder (own differentiator → direct competitors' reviews → marketplace comparables → adjacent brands sharing the audience) with provisional-persona tagging and replacement as first-party evidence arrives.
- **marketing-loops** (1.1.0 → 1.2.0): added **the monthly-creative-retro loop** to the Paid section of `references/loop-catalog.md` — closes ad-creative's Mode 4 loop on a schedule: pulls last month's performance, drafts the retro artifact and next month's capacity-checked slate, flags the account-state call for human confirmation, one-retro-per-month idempotency, and never launches or pauses ads. Closes #434.
### 2.8.6 (2026-07-09)
- **ai-seo** (2.1.0 → 2.2.0): added **citations vs. recommendations** — the correction to citation-centric AEO strategy. New `references/citations-vs-recommendations.md` (grounded in Lily Ray's (Amsive) 100-query B2B study, Scrunch and SimilarWeb behavioral studies, and Growth Plays commentary): the **AI visibility ladder** (retrieved → cited → mentioned → recommended, each governed by different criteria, plus the shadow rung of being *recommended against* on requirements-heavy prompts), the **self-promotional listicle risk** (69% of the AI Overview citations earned by self-promotional "best [category]" listicles — 224 of 323 — appeared in answers that excluded the publisher from the recommendations; for emerging brands a self-ranked guide can act as a vote for competitors), **stage-dependent buyer's-guide strategy** (leaders get cited and recommended; emerging brands get citation and category framing — still worth publishing, with rebalanced expectations), **what earns recommendations** (offsite consensus: reviews, analysts, communities, earned media, video — with the test "if a model ignored everything on our domain, would the rest of the web still shortlist us?"), and **what a recommendation is worth** (Scrunch, observational: ~2× behavior lift vs. a passing mention; for users with no recent observed brand engagement, +182% branded searches / +117% site visits / +185% product views within a week; SimilarWeb: ~2.5× more new visitors — with only ~9% visible as AI traffic, the attribution blind spot) plus the measurement triad (prompt tracking with mention framing, self-reported attribution, call recordings). SKILL.md adds a compact citation-≠-recommendation pointer, a Recommendation-rate row in Monitoring, and caveats on the Listicle Block (content-patterns.md) and educational-content goals (content-types.md).
+11 -4
View File
@@ -1,8 +1,8 @@
---
name: ad-creative
description: "When the user wants to generate, iterate, or scale ad creative — headlines, descriptions, primary text, or full ad variations — for any paid advertising platform. Also use when the user mentions 'ad copy variations,' 'ad creative,' 'generate headlines,' 'RSA headlines,' 'bulk ad copy,' 'ad iterations,' 'creative testing,' 'ad performance optimization,' 'write me some ads,' 'Facebook ad copy,' 'Google ad headlines,' 'LinkedIn ad text,' 'static ads,' 'static ad concepts,' 'ad templates,' 'iMessage ad,' 'chat reveal ad,' 'text message ad,' 'fake DM ad,' 'ChatGPT ad,' 'Apple Notes ad,' 'motion video ad,' 'faceless video ad,' 'animated explainer ad,' 'motion collage ad,' or 'I need more ad variations.' Use this whenever someone needs to produce ad copy at scale or iterate on existing ads. For campaign strategy and targeting, see ads. For landing page copy, see copywriting."
description: "When the user wants to generate, iterate, or scale ad creative — headlines, descriptions, primary text, or full ad variations — for any paid advertising platform. Also use when the user mentions 'ad copy variations,' 'ad creative,' 'generate headlines,' 'RSA headlines,' 'bulk ad copy,' 'ad iterations,' 'creative testing,' 'ad performance optimization,' 'write me some ads,' 'Facebook ad copy,' 'Google ad headlines,' 'LinkedIn ad text,' 'static ads,' 'static ad concepts,' 'ad templates,' 'iMessage ad,' 'chat reveal ad,' 'text message ad,' 'fake DM ad,' 'ChatGPT ad,' 'Apple Notes ad,' 'creative strategy,' 'creative roadmap,' 'creative retro,' 'hook writing,' 'creative review page,' 'present ad creative for approval,' 'motion video ad,' 'faceless video ad,' 'animated explainer ad,' 'motion collage ad,' or 'I need more ad variations.' Use this whenever someone needs to produce ad copy at scale or iterate on existing ads. For campaign strategy and targeting, see ads. For landing page copy, see copywriting."
metadata:
version: 2.5.0
version: 2.7.0
---
# Ad Creative
@@ -46,7 +46,7 @@ Gather this context (ask if not provided):
## How This Skill Works
This skill supports three modes:
This skill supports four modes:
### Mode 1: Generate from Scratch
When starting fresh, you generate a full set of ad creative based on product context, audience insights, and platform best practices.
@@ -61,7 +61,10 @@ Pull performance data → Identify winning patterns → Generate new variations
```
### Mode 3: Scaled Static Batches (Grounded)
For recurring static ad production at volume (e.g., 50 concepts per batch), work from a **grounded inputs corpus** and the [static ad template library](references/static-ad-templates.md). Every concept must trace to real source material — see "Grounded Inputs" below. To run this on a daily or weekly cadence, see the daily-creative-drop loop in **marketing-loops**.
For recurring static ad production at volume (e.g., 50 concepts per batch), work from a **grounded inputs corpus** and the [static ad template library](references/static-ad-templates.md). Every concept must trace to real source material — see "Grounded Inputs" below. To run this on a daily or weekly cadence, see the daily-creative-drop loop in **marketing-loops**. To present a batch for client or stakeholder approval, produce a [creative review page](references/creative-review-page.md).
### Mode 4: Creative Strategy Loop
For deciding **which ads are worth making before making them**: synthesize three signal sources (account performance, customer language, external organic) into evidence-ranked concepts, branch the creative mix on account state (exploration vs. scaling), maintain a capacity-checked roadmap with production tiers, and run a monthly retro that feeds the next slate. The full system lives in [references/creative-roadmap.md](references/creative-roadmap.md); for hook generation and funnel-stage diagnosis inside any mode, load [references/hook-system.md](references/hook-system.md).
---
@@ -321,6 +324,10 @@ outputs/YYYY-MM-DD/
Per-concept format is defined in [references/static-ad-templates.md](references/static-ad-templates.md). The human workflow this supports: open the folder, scan INDEX.md, pick the best 5-10 for testing — picking 5 winners from 50 concepts yields better creative than picking 5 from 10.
### Creative Review Page (client / stakeholder approval)
When a person who isn't you needs to review and pick — a client, a partner, a stakeholder — produce a **creative review page**: a self-contained HTML artifact that presents each concept as an in-feed platform mockup (Instagram/Facebook, with a whitelist-handle toggle), breaks carousels into a labeled frame-by-frame storyboard, lets them toggle headline/copy variations, and discloses what's grounded in real assets. It's the visual upgrade to INDEX.md — a decision made off one link instead of by reading markdown. The template ships at [assets/creative-review-template.html](assets/creative-review-template.html) (one file, no build, hostable anywhere); populate its `DATA` object from your generated concepts. Full data model, grounding rules (the disclosure block is required), and delivery in [references/creative-review-page.md](references/creative-review-page.md).
### Iteration Report
When iterating, include a summary:
@@ -0,0 +1,400 @@
<!DOCTYPE html>
<!--
Creative Review Page — a shareable ad-creative approval artifact.
HOW TO USE (agents): replace the JSON inside <script id="review-data"> below
with the real project. Everything else renders from it. The file is
self-contained — no build, no network, no dependencies. Open it in a browser,
host it on any static host (Vercel/Netlify/GitHub Pages), or hand off the
single .html file.
THE DATA BLOCK IS JSON, NOT JAVASCRIPT:
- double-quoted keys and strings, no comments, no trailing commas
- it is inert data (parsed with JSON.parse), so a value can never execute
- SECURITY: escape every literal "<" in your text values as < so a
value like "</script>" can never break out of the tag. All values are
also HTML-escaped again at render time.
DATA SHAPE — see references/creative-review-page.md for the annotated spec.
Images: each frame's "image" may be a URL, a relative path, or a data URI.
If omitted (or the file is missing), a placeholder shows the frame label +
the image prompt — use this for concepts not yet rendered to image.
-->
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<title>Creative Review</title>
<style>
:root {
--bg: #f4f3f0; --card: #ffffff; --ink: #16150f; --muted: #6b6a63;
--line: #e4e2dc; --accent: #2f6fed; --accent-soft: #eaf0fe;
--radius: 14px; --shadow: 0 1px 2px rgba(0,0,0,.04), 0 8px 24px rgba(0,0,0,.05);
}
* { box-sizing: border-box; }
body { margin: 0; background: var(--bg); color: var(--ink);
font: 15px/1.5 -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif;
-webkit-font-smoothing: antialiased; }
.wrap { max-width: 1120px; margin: 0 auto; padding: 32px 20px 80px; }
.eyebrow { font-size: 11px; font-weight: 700; letter-spacing: .12em; text-transform: uppercase; color: var(--muted); }
a { color: var(--accent); }
header.project { margin-bottom: 28px; }
header.project h1 { font-size: 20px; margin: 6px 0 2px; letter-spacing: -.01em; }
header.project .sub { color: var(--muted); font-size: 13px; }
.concepts { display: grid; grid-template-columns: repeat(auto-fit, minmax(210px, 1fr)); gap: 10px; margin: 14px 0 28px; }
.concept { text-align: left; background: var(--card); border: 1.5px solid var(--line); border-radius: var(--radius);
padding: 14px 16px; cursor: pointer; transition: border-color .12s, box-shadow .12s; font: inherit; color: inherit; }
.concept:hover { border-color: #cfcdc6; }
.concept[aria-selected="true"] { border-color: var(--accent); box-shadow: 0 0 0 3px var(--accent-soft); background: #fff; }
.concept .row1 { display: flex; align-items: baseline; justify-content: space-between; gap: 8px; }
.concept .num { font-size: 11px; font-weight: 700; color: var(--muted); }
.concept .frames { font-size: 11px; color: var(--muted); }
.concept .name { font-weight: 650; font-size: 15px; margin: 4px 0 3px; }
.concept .tag { font-size: 12.5px; color: var(--muted); line-height: 1.35; }
.grid { display: grid; grid-template-columns: minmax(0, 380px) minmax(0, 1fr); gap: 28px; align-items: start; }
@media (max-width: 860px) { .grid { grid-template-columns: 1fr; } }
.col-label { margin-bottom: 10px; }
.toggles { display: flex; flex-wrap: wrap; gap: 14px; margin-bottom: 12px; }
.seg { display: inline-flex; background: #ecebe6; border-radius: 999px; padding: 3px; }
.seg button { border: 0; background: transparent; font: inherit; font-size: 12.5px; font-weight: 600; color: var(--muted);
padding: 5px 12px; border-radius: 999px; cursor: pointer; }
.seg button[aria-pressed="true"] { background: #fff; color: var(--ink); box-shadow: 0 1px 2px rgba(0,0,0,.08); }
.seg .lbl { align-self: center; font-size: 10.5px; font-weight: 700; letter-spacing: .1em; text-transform: uppercase; color: var(--muted); margin-right: 6px; }
.post { background: var(--card); border: 1px solid var(--line); border-radius: 12px; overflow: hidden; box-shadow: var(--shadow); }
.post .top { display: flex; align-items: center; gap: 10px; padding: 11px 12px; }
.post .avatar { width: 34px; height: 34px; border-radius: 50%; background: var(--accent-soft); color: var(--accent);
display: grid; place-items: center; font-weight: 700; font-size: 13px; overflow: hidden; flex: none; }
.post .avatar img { width: 100%; height: 100%; object-fit: cover; }
.post .who { line-height: 1.2; }
.post .who .name { font-weight: 650; font-size: 13.5px; }
.post .who .partner { font-size: 11.5px; color: var(--muted); }
.post .dots { margin-left: auto; color: var(--muted); font-weight: 700; letter-spacing: 2px; }
.frame { position: relative; aspect-ratio: 4/5; background: #ded9d0; display: grid; }
.frame img { width: 100%; height: 100%; object-fit: cover; grid-area: 1/1; z-index: 1; }
.frame .ph { grid-area: 1/1; display: flex; flex-direction: column; justify-content: space-between; padding: 16px;
background: linear-gradient(135deg,#efece5,#e2ddd2); }
.frame .ph .plabel { font-size: 11px; font-weight: 700; letter-spacing: .1em; text-transform: uppercase; color: #948e80; }
.frame .ph .pprompt { font-size: 13px; color: #5f5a4e; line-height: 1.4; }
.frame .badge { position: absolute; top: 12px; left: 12px; z-index: 2; background: rgba(255,255,255,.92);
font-size: 11.5px; font-weight: 600; padding: 5px 10px; border-radius: 999px; display: flex; align-items: center; gap: 5px; }
.frame .counter { position: absolute; top: 12px; right: 12px; z-index: 2; background: rgba(0,0,0,.6); color: #fff; font-size: 11px;
font-weight: 600; padding: 3px 9px; border-radius: 999px; }
.frame .headline { position: absolute; left: 0; right: 0; bottom: 0; z-index: 2; padding: 18px 16px 20px; color: #fff;
font-size: 21px; font-weight: 700; line-height: 1.2; letter-spacing: -.01em;
background: linear-gradient(to top, rgba(0,0,0,.72), rgba(0,0,0,0)); }
.frame .headline.light { color: var(--ink); background: linear-gradient(to top, rgba(255,255,255,.85), rgba(255,255,255,0)); }
/* Instagram chrome */
.ig-cta { display: flex; align-items: center; justify-content: space-between; padding: 12px; border-top: 1px solid var(--line);
font-weight: 600; font-size: 13.5px; }
.ig-cta .chev { color: var(--muted); }
.ig-actions { display: flex; gap: 16px; padding: 10px 12px 2px; color: #26251f; }
.ig-actions svg { width: 22px; height: 22px; }
.ig-actions .save { margin-left: auto; }
.likes { padding: 6px 12px 2px; font-weight: 650; font-size: 13px; }
.caption { padding: 2px 12px 14px; font-size: 13px; line-height: 1.4; }
.caption .h { font-weight: 650; }
.caption .more { color: var(--muted); }
/* Facebook chrome — link card below image + text actions */
.fb-card { display: flex; align-items: center; gap: 12px; padding: 12px; background: #f3f4f6; border-top: 1px solid var(--line); }
.fb-card .meta { min-width: 0; flex: 1; }
.fb-card .dom { font-size: 11px; letter-spacing: .04em; text-transform: uppercase; color: var(--muted); }
.fb-card .hl { font-size: 14px; font-weight: 650; line-height: 1.25; margin-top: 2px; overflow: hidden; }
.fb-card .btn { flex: none; background: #e4e6eb; color: #050505; font-weight: 650; font-size: 12.5px; padding: 8px 14px; border-radius: 7px; }
.fb-actions { display: flex; padding: 4px 12px; border-top: 1px solid var(--line); }
.fb-actions span { flex: 1; text-align: center; padding: 8px 0; font-size: 13px; font-weight: 600; color: var(--muted); }
.board { background: var(--card); border: 1px solid var(--line); border-radius: var(--radius); padding: 16px; box-shadow: var(--shadow); margin-bottom: 20px; }
.board .frames-grid { display: grid; grid-template-columns: repeat(3, 1fr); gap: 12px; margin-top: 12px; }
@media (max-width: 480px) { .board .frames-grid { grid-template-columns: repeat(2, 1fr); } }
.thumb { border: 0; background: transparent; padding: 0; cursor: pointer; text-align: left; font: inherit; color: inherit; }
.thumb .box { aspect-ratio: 4/5; border-radius: 9px; overflow: hidden; border: 2px solid transparent; background: #e7e2d8;
display: grid; transition: border-color .12s; }
.thumb[aria-current="true"] .box { border-color: var(--accent); }
.thumb .box img { width: 100%; height: 100%; object-fit: cover; grid-area: 1/1; z-index: 1; }
.thumb .box .mini { grid-area: 1/1; padding: 8px; font-size: 10.5px; color: #7a7566; line-height: 1.3;
background: linear-gradient(135deg,#efece5,#e2ddd2); overflow: hidden; }
.thumb .cap { margin-top: 6px; font-size: 12px; }
.thumb .cap .n { color: var(--muted); font-weight: 700; margin-right: 6px; }
.copy { background: var(--card); border: 1px solid var(--line); border-radius: var(--radius); padding: 18px; box-shadow: var(--shadow); }
.copy .block { padding: 14px 0; border-top: 1px solid var(--line); }
.copy .block:first-of-type { border-top: 0; padding-top: 4px; }
.headline-opt { display: flex; gap: 10px; align-items: flex-start; width: 100%; text-align: left; font: inherit; color: inherit;
background: #faf9f6; border: 1.5px solid var(--line); border-radius: 10px; padding: 11px 13px; cursor: pointer; margin-top: 8px; }
.headline-opt[aria-pressed="true"] { border-color: var(--accent); background: #fff; box-shadow: 0 0 0 3px var(--accent-soft); }
.headline-opt .n { font-size: 11px; font-weight: 700; color: var(--muted); margin-top: 2px; }
.headline-opt .t { font-size: 14px; line-height: 1.35; }
.kv { font-size: 13.5px; line-height: 1.5; }
.kv .dest { color: var(--accent); font-family: ui-monospace, SFMono-Regular, Menlo, monospace; font-size: 13px; }
.steps { margin: 8px 0 0; padding: 0; list-style: none; }
.steps li { display: flex; gap: 10px; padding: 5px 0; font-size: 13px; line-height: 1.4; }
.steps li .i { flex: none; width: 20px; height: 20px; border-radius: 50%; background: var(--accent-soft); color: var(--accent);
display: grid; place-items: center; font-size: 11px; font-weight: 700; }
.grounding { background: #f6f5ef; border: 1px dashed #cfcabb; border-radius: 10px; padding: 12px 14px; font-size: 12.5px; color: #5f5a4e; line-height: 1.45; margin-top: 8px; }
.err { background: #fbeaea; border: 1px solid #e6b7b7; color: #8a2b2b; border-radius: 10px; padding: 14px 16px; font-size: 13px; }
footer { margin-top: 40px; text-align: center; font-size: 12px; color: var(--muted); }
</style>
</head>
<body>
<!-- DATA — replace this JSON with your project (see the comment at the top of the file). -->
<script type="application/json" id="review-data">
{
"project": {
"brand": "Truvani",
"agency": "Light Labs",
"date": "2026-07-12",
"note": "Whitelisted paid-social concepts for review"
},
"platforms": ["instagram", "facebook"],
"concepts": [
{
"name": "Heavy-Metal Proof",
"tagline": "Lifestyle hero, then the lab results",
"handles": [
{ "name": "truvani", "partner": "Paid partnership with lightlabs", "initials": "TV" },
{ "name": "Light Labs", "partner": "Paid partnership with truvani", "initials": "LL" }
],
"frames": [
{ "label": "Hook", "prompt": "Product bag hero on soft pink, gold-lace overlay", "headline": "Finally — a plant-based protein that's third-party tested for heavy metals.", "headlineTheme": "dark" },
{ "label": "The problem", "prompt": "Editorial card: 'Plants absorb more than nutrients' + Pb/As/Cd chips" },
{ "label": "Enter Light Labs", "prompt": "Clean card: 'So we sent it to Light Labs' + independent-lab note" },
{ "label": "The results", "prompt": "Results table: Arsenic / Cadmium / Lead, all within limits, green check" },
{ "label": "For context", "prompt": "'Less arsenic than your breakfast' comparison bar" },
{ "label": "The ask", "prompt": "Product you can finally trust — CTA frame", "headline": "Protein you can finally trust." }
],
"headlines": [
"Finally — a plant-based protein that's third-party tested for heavy metals.",
"We tested our protein for heavy metals. Here's what an independent lab found.",
"Most protein powders are never tested for heavy metals. Ours is."
],
"primaryText": "We tested our Plant-Based Protein for the heavy metals that hide in “clean” powders — lead, arsenic and cadmium. Here's exactly what an independent lab measured.",
"destination": { "url": "shop.truvani.com", "cta": "Shop now", "offer": "72% OFF Protein Starter Kit" },
"rollout": {
"title": "How the whitelist runs",
"steps": [
"Truvani reviews and approves the creative — Light Labs builds it.",
"Truvani sends a Meta partnership request granting Light Labs access to this ad only.",
"Light Labs launches it under the co-branded handle.",
"We report performance back — framed as a free, mutually beneficial first test."
]
},
"grounding": "Results are Truvani's actual Light Labs panel (Vanilla, tested Nov 13, 2025). Imagery is Truvani's own product & lifestyle photography."
},
{
"name": "Cleaner Than Rice",
"tagline": "Leads with the brown-rice comparison",
"frames": [
{ "label": "Hook", "prompt": "Split visual: brown rice vs protein scoop", "headline": "Your “clean” brown rice protein? Test it.", "headlineTheme": "dark" },
{ "label": "The claim", "prompt": "Stat card comparing arsenic levels" },
{ "label": "The proof", "prompt": "Light Labs results table" },
{ "label": "The context", "prompt": "What the numbers mean, plainly" },
{ "label": "The ask", "prompt": "Starter-kit offer frame", "headline": "Trust the label. Then trust the test." }
],
"headlines": [
"Your “clean” brown rice protein? Test it.",
"Brown rice protein is often the worst offender for arsenic. We checked ours.",
"“Plant-based” doesn't mean “clean.” We have the lab panel to prove ours is."
],
"primaryText": "Brown-rice protein is one of the most common sources of dietary arsenic. So we sent ours to an independent lab. Here's the panel.",
"destination": { "url": "shop.truvani.com", "cta": "Shop now", "offer": "72% OFF Protein Starter Kit" },
"grounding": "Comparison figures are from Truvani's Light Labs panel and published dietary-arsenic ranges. No competitor is named."
}
]
}
</script>
<div class="wrap">
<header class="project" id="project"></header>
<div class="eyebrow">Creative concept · toggle between ideas</div>
<div class="concepts" id="concepts" role="tablist"></div>
<div class="grid">
<section>
<div class="eyebrow col-label" id="preview-label">In-feed preview</div>
<div class="toggles" id="toggles"></div>
<div class="post" id="post"></div>
</section>
<section>
<div class="board">
<div class="eyebrow" id="board-label">Storyboard · tap to jump</div>
<div class="frames-grid" id="frames-grid"></div>
</div>
<div class="copy" id="copy"></div>
</section>
</div>
<footer id="footer"></footer>
</div>
<script>
/* ============================================================================
RENDER — generic; no need to edit when swapping the DATA JSON above.
========================================================================== */
const esc = (s) => String(s == null ? "" : s).replace(/[&<>"']/g, c => (
{ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" }[c]));
const PLATFORMS = { instagram: "Instagram", facebook: "Facebook" };
let DATA;
try {
DATA = JSON.parse(document.getElementById("review-data").textContent);
} catch (e) {
document.querySelector(".wrap").innerHTML =
'<div class="err"><b>Couldn\'t read the review data.</b><br/>The <code>#review-data</code> block must be valid JSON — double-quoted keys and strings, no comments, no trailing commas. Parser said: ' + esc(e.message) + '</div>';
throw e;
}
const state = { concept: 0, frame: 0, platform: null, handle: 0, headline: 0 };
const concept = () => DATA.concepts[state.concept];
// platforms restricted to the ones we can render; default to first valid
const platformList = () => (DATA.platforms || ["instagram"]).filter(p => PLATFORMS[p]);
state.platform = platformList()[0] || "instagram";
const heart = '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8"><path d="M20.8 4.6a5.5 5.5 0 0 0-7.8 0L12 5.6l-1-1a5.5 5.5 0 1 0-7.8 7.8l1 1L12 21l7.8-7.6 1-1a5.5 5.5 0 0 0 0-7.8z"/></svg>';
const comment = '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8"><path d="M21 11.5a8.4 8.4 0 0 1-11.8 7.7L3 21l1.9-6.2A8.4 8.4 0 1 1 21 11.5z"/></svg>';
const share = '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8"><path d="M22 2 11 13M22 2l-7 20-4-9-9-4 20-7z"/></svg>';
const bookmark = '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8"><path d="M19 21l-7-5-7 5V5a2 2 0 0 1 2-2h10a2 2 0 0 1 2 2z"/></svg>';
function renderProject() {
const p = DATA.project || {};
const line = [p.brand, p.agency && `× ${p.agency}`].filter(Boolean).join(" ");
document.getElementById("project").innerHTML =
`<div class="eyebrow">Creative review${p.date ? " · " + esc(p.date) : ""}</div>
<h1>${esc(line || "Ad creative")}</h1>${p.note ? `<div class="sub">${esc(p.note)}</div>` : ""}`;
document.getElementById("footer").innerHTML =
`Creative review${p.agency ? " · " + esc(p.agency) : ""} — concepts for approval. Nothing here is live until you pick.`;
}
function renderConcepts() {
document.getElementById("concepts").innerHTML = DATA.concepts.map((c, i) => `
<button class="concept" role="tab" aria-selected="${i === state.concept}" data-i="${i}">
<div class="row1"><span class="num">${String(i + 1).padStart(2, "0")}</span>
<span class="frames">${c.frames.length} frame${c.frames.length === 1 ? "" : "s"}</span></div>
<div class="name">${esc(c.name)}</div>
<div class="tag">${esc(c.tagline || "")}</div>
</button>`).join("");
document.querySelectorAll(".concept").forEach(b =>
b.onclick = () => { state.concept = +b.dataset.i; state.frame = 0; state.handle = 0; state.headline = 0; renderAll(); });
}
function handles() {
return concept().handles || [{
name: DATA.project?.brand || "brand",
partner: DATA.project?.agency ? "Paid partnership with " + DATA.project.agency.toLowerCase() : "Sponsored",
initials: (DATA.project?.brand || "AD").slice(0, 2).toUpperCase()
}];
}
function renderToggles() {
const plats = platformList(), hs = handles();
let html = "";
if (plats.length > 1) {
html += `<div class="seg" role="group">${plats.map(p =>
`<button data-plat="${esc(p)}" aria-pressed="${p === state.platform}">${esc(PLATFORMS[p])}</button>`).join("")}</div>`;
}
if (hs.length > 1) {
html += `<div class="seg" role="group"><span class="lbl">Handle</span>${hs.map((h, i) =>
`<button data-handle="${i}" aria-pressed="${i === state.handle}">${esc(h.name)}</button>`).join("")}</div>`;
}
const el = document.getElementById("toggles");
el.innerHTML = html;
el.querySelectorAll("[data-plat]").forEach(b => b.onclick = () => { state.platform = b.dataset.plat; renderToggles(); renderPost(); });
el.querySelectorAll("[data-handle]").forEach(b => b.onclick = () => { state.handle = +b.dataset.handle; renderToggles(); renderPost(); });
document.getElementById("preview-label").textContent = (hs.length > 1 ? "Whitelisted ad · " : "") + "In-feed preview";
}
// placeholder underneath + image on top; a missing/broken image removes itself → placeholder shows
function frameVisual(f, phCls) {
const ph = `<div class="${phCls}"><div class="plabel">${esc(f.label)}</div><div class="pprompt">${esc(f.prompt || "")}</div></div>`;
const img = f.image ? `<img src="${esc(f.image)}" alt="${esc(f.label)}" onerror="this.remove()" />` : "";
return ph + img;
}
function frameHTML(c, f) {
const total = c.frames.length;
const headlineText = state.frame === 0 ? (c.headlines?.[state.headline] || f.headline || "") : (f.headline || "");
const theme = f.headlineTheme === "light" ? " light" : "";
return `<div class="frame">
${frameVisual(f, "ph")}
<span class="counter">${state.frame + 1}/${total}</span>
${headlineText ? `<div class="headline${theme}">${esc(headlineText)}</div>` : ""}
</div>`;
}
function renderPost() {
const c = concept(), f = c.frames[state.frame], h = handles()[state.handle] || handles()[0];
const dest = c.destination || {};
const top = `<div class="top">
<div class="avatar">${h.initials ? esc(h.initials) : ""}</div>
<div class="who"><div class="name">${esc(h.name)}</div><div class="partner">${esc(h.partner || "Sponsored")}</div></div>
<div class="dots">···</div>
</div>`;
let chrome;
if (state.platform === "facebook") {
const domain = dest.url ? esc(dest.url) : "";
const hl = c.headlines?.[state.headline] || f.headline || dest.offer || "";
chrome = `<div class="fb-card">
<div class="meta"><div class="dom">${domain}</div><div class="hl">${esc(hl)}</div></div>
${dest.cta ? `<div class="btn">${esc(dest.cta)}</div>` : ""}
</div>
<div class="fb-actions"><span>Like</span><span>Comment</span><span>Share</span></div>`;
} else {
chrome = `<div class="ig-cta"><span>${esc(dest.cta || "Learn more")}</span><span class="chev">›</span></div>
<div class="ig-actions">${heart}${comment}${share}<span class="save">${bookmark}</span></div>
<div class="likes">6,240 likes</div>
<div class="caption"><span class="h">${esc(h.name)}</span> ${esc((c.primaryText || "").slice(0, 90))}<span class="more"> … more</span></div>`;
}
document.getElementById("post").innerHTML = top + frameHTML(c, f) + chrome;
document.getElementById("board-label").textContent = `${c.name} · ${state.frame + 1}/${c.frames.length} · tap to jump`;
}
function renderBoard() {
const c = concept();
document.getElementById("frames-grid").innerHTML = c.frames.map((f, i) => `
<button class="thumb" aria-current="${i === state.frame}" data-i="${i}">
<div class="box">${frameVisual(f, "mini")}</div>
<div class="cap"><span class="n">${String(i + 1).padStart(2, "0")}</span>${esc(f.label)}</div>
</button>`).join("");
document.querySelectorAll(".thumb").forEach(b =>
b.onclick = () => { state.frame = +b.dataset.i; renderPost(); renderBoard(); });
}
function renderCopy() {
const c = concept(), dest = c.destination || {};
let html = "";
if (c.headlines?.length) {
html += `<div class="block"><div class="eyebrow">Headline — tap to preview</div>${c.headlines.map((h, i) =>
`<button class="headline-opt" aria-pressed="${i === state.headline}" data-i="${i}">
<span class="n">${String(i + 1).padStart(2, "0")}</span><span class="t">${esc(h)}</span></button>`).join("")}</div>`;
}
if (c.primaryText) html += `<div class="block"><div class="eyebrow">Primary text</div><div class="kv" style="margin-top:8px">${esc(c.primaryText)}</div></div>`;
if (dest.url || dest.cta) {
html += `<div class="block"><div class="eyebrow">Destination</div><div class="kv" style="margin-top:8px">
${dest.url ? `<span class="dest">${esc(dest.url)}</span><br/>` : ""}
${dest.cta ? `CTA: ${esc(dest.cta)}` : ""}${dest.offer ? ` → ${esc(dest.offer)}` : ""}</div></div>`;
}
if (c.rollout?.steps?.length) {
html += `<div class="block"><div class="eyebrow">${esc(c.rollout.title || "How it runs")}</div>
<ol class="steps">${c.rollout.steps.map((s, i) => `<li><span class="i">${i + 1}</span><span>${esc(s)}</span></li>`).join("")}</ol></div>`;
}
if (c.grounding) html += `<div class="block"><div class="eyebrow">Live data · real assets</div><div class="grounding">${esc(c.grounding)}</div></div>`;
const el = document.getElementById("copy");
el.innerHTML = html;
el.querySelectorAll(".headline-opt").forEach(b =>
b.onclick = () => { state.headline = +b.dataset.i; state.frame = 0; renderPost(); renderBoard(); renderCopy(); });
}
function renderAll() { renderConcepts(); renderToggles(); renderPost(); renderBoard(); renderCopy(); }
renderProject();
renderAll();
</script>
</body>
</html>
+30
View File
@@ -115,6 +115,36 @@
"Gives surface-selection reasoning (ChatGPT vs Notes) instead of treating formats as interchangeable"
],
"files": []
},
{
"id": 9,
"prompt": "Our Meta account is stuck — we've tested 30 ads over two months and nothing beats the control. I have our reviews exported and access to our ad account data. Build me a creative plan for next month.",
"expected_output": "Should apply Mode 4 / references/creative-roadmap.md rather than jumping straight to generating ads. Should identify the account as exploration state (nothing working) and shape the plan accordingly: mostly net-new concepts across different segments/angles, minimal iterations, per-metric win redefinition (a hold-rate lift or CPC drop counts as a hit worth pulling on). Should synthesize the three signals (account performance from the ad data, customer language from the reviews, external organic — asking for or mining niche organic content) into concepts ranked by evidence tier, each with a cited source. Should produce a capacity-checked monthly slate with production tiers (favoring T1/T2 low-fidelity tests per the fidelity ladder) and flag the common exploration-state root causes to check (boring creative, overcomplicated message, unclear UVP, punishing CPMs). Should end with the retro plan for judging the slate at month end. Should not invent customer language or claims — insights must trace to the provided reviews/data.",
"assertions": [
"Applies the creative strategy loop (Mode 4) instead of only generating ad copy",
"Diagnoses exploration state and recommends a wide, net-new-heavy mix with minimal iterations",
"Redefines wins per-metric for a stuck account",
"Synthesizes all three signal sources or explicitly requests the missing one",
"Concepts are evidence-ranked with cited sources (no invented insights)",
"Monthly slate is capacity-checked and production-tiered, favoring low-fidelity tests",
"Includes a month-end retro plan that feeds the next slate"
],
"files": []
},
{
"id": 10,
"prompt": "We generated four ad concepts for a client (an organic skincare brand) and need to send them something they can actually look at and approve — with the Instagram preview, the carousel frames, and the different headline options they can compare. Can you put that together?",
"expected_output": "Should recognize this as a creative review page request and apply references/creative-review-page.md + the assets/creative-review-template.html template rather than producing plain markdown. Should copy the template into the output folder and populate its DATA object with the four concepts as tabs, each with an in-feed Instagram preview, a labeled frame-by-frame storyboard (frames labeled by narrative job — Hook / Problem / Proof / Ask — not by pictured content), selectable headline variations, primary text, and destination/CTA. Should curate to a reviewable number of concepts (2-4) rather than dumping everything. Should include a required grounding disclosure per concept stating what is real (product photography, any claims/results) and label illustrative proof as illustrative — never present invented stats or stock imagery as the brand's own. Should use styled placeholders for frames not yet rendered to image, and keep image paths relative. Should explain how to deliver it (open locally, host on a static host, or hand off the file).",
"assertions": [
"Produces a creative review page from the HTML template, not plain markdown",
"Populates the DATA object (concept tabs, in-feed preview, frame storyboard, headline variations, copy, destination)",
"Labels storyboard frames by narrative job rather than by pictured content",
"Includes a required grounding/disclosure line per concept; labels illustrative proof as illustrative",
"Does not present invented stats or stock imagery as the brand's real assets",
"Uses placeholders for unrendered frames and keeps image paths relative",
"Explains how to deliver the page (open locally / host / hand off the file)"
],
"files": []
}
]
}
@@ -0,0 +1,106 @@
# The Creative Review Page
A shareable, self-contained web page that presents generated ad concepts for a client or stakeholder to **review and pick** — the visual upgrade to `INDEX.md`. Where the markdown outputs are built for the operator, the review page is built for the person approving the spend: it shows each concept as an in-feed platform mockup, breaks carousels into a labeled frame-by-frame storyboard, lets them toggle copy variations, and discloses what's grounded in real assets.
The template ships at [assets/creative-review-template.html](../assets/creative-review-template.html). It's one file — inline CSS and JS, no build, no dependencies, no network. Open it locally, host it on any static host (Vercel/Netlify/GitHub Pages), or hand off the `.html` file directly.
## When to produce one
- **Presenting a batch for approval** — after Mode 1 or Mode 3 generation, package the top concepts into a review page instead of (or alongside) `INDEX.md`. Picking 5 of 50 is a *visual* decision; a client shouldn't have to read markdown to make it.
- **Pitching a whitelist / co-branded partnership** — the format the source pattern was built for: show the partner exactly what the ad looks like under each handle, with the rollout mechanics spelled out.
- **A monthly slate review** (Mode 4) — render the slate's concepts so the account-state call and the pick happen off one link.
Don't produce one for a single headline tweak or a quick internal gut-check — the markdown output is faster. Reach for the review page when a human who isn't you needs to choose.
## How it's built
The template renders entirely from a JSON block near the top of the file — `<script type="application/json" id="review-data">`. Populate it from your generated concepts and everything else renders — tabs, previews, storyboard, copy panel. You do not edit the render code below the data block. The annotated model below is shown with `//` comments for readability; **the file itself is strict JSON** — no comments, no trailing commas (see "Populating the data safely").
### Data model
```jsonc
{
project: {
brand: "Truvani", // required
agency: "Light Labs", // optional — adds the co-brand line + the default handle fallback (partner label/initials)
date: "2026-07-12", // optional
note: "one-line context" // optional
},
platforms: ["instagram", "facebook"], // previews to offer; first is the default. Supported: instagram, facebook
concepts: [ // each concept is one strategic ANGLE (see SKILL.md "Define Your Angles")
{
name: "Heavy-Metal Proof", // required — the angle name
tagline: "Lifestyle hero, then the lab results", // one line, what makes this concept distinct
handles: [ // optional. 1 entry = normal post; 2 = whitelist handle toggle
{ name: "truvani", partner: "Paid partnership with lightlabs", initials: "TV" },
{ name: "Light Labs", partner: "Paid partnership with truvani", initials: "LL" }
],
frames: [ // 1 frame = single ad; multiple = carousel storyboard
{
label: "Hook", // the frame's job in the narrative arc
prompt: "Product bag hero on soft pink, gold-lace overlay", // image description (shown as placeholder if no image)
image: "images/heavy-metal-01.png", // optional — URL, relative path, or data URI; omit for text-only concepts
headline: "Finally — a plant-based protein that's third-party tested for heavy metals.", // optional per-frame overlay
headlineTheme: "dark" // optional: "dark" (default, white text) or "light" (dark text on light imagery)
}
// … one object per frame
],
headlines: [ // selectable variations; the picked one overlays frame 1 in the preview
"Finally — a plant-based protein that's third-party tested for heavy metals.",
"We tested our protein for heavy metals. Here's what an independent lab found.",
"Most protein powders are never tested for heavy metals. Ours is."
],
primaryText: "The caption / body copy.",
destination: { url: "shop.truvani.com", cta: "Shop now", offer: "72% OFF Protein Starter Kit" },
rollout: { // optional — the mechanics of how this runs (whitelist, launch plan)
title: "How the whitelist runs",
steps: ["step 1", "step 2", "…"]
},
grounding: "What in this concept is real — the required disclosure. See below."
}
// … 2–4 concepts is the sweet spot; more than that and the tabs stop being a decision
]
}
```
### The frame storyboard = a carousel narrative arc
A concept's `frames` are its storyboard. Label each frame by the *job it does*, not its content — `Hook`, `The problem`, `The results`, `The ask`. This is the same narrative-arc thinking as the carousel frameworks: a proof-led concept is literally Hook → Problem → Mechanism → Results → Context → Ask. For the five reusable carousel arcs (Value-Stack, Problem-Proof, Hack List, Rant Callout, Demo Walkthrough), see `carousel-frameworks.md` in the **social** skill and pick the arc that fits the angle before writing frames.
### Images vs. placeholders
Every frame renders one of two ways:
- **`image` provided** — the real creative (from the Mode 3 `images/` folder, a hosted URL, or a data URI) fills the frame.
- **`image` omitted** — a styled placeholder shows the frame `label` + `prompt`. This is the intended state for concepts that are copy + image-prompt but not yet rendered to image — the review page is useful *before* images exist, and stays useful as they get filled in.
Ship review pages with placeholders freely; they communicate the concept. Swap in images as they're generated.
## Grounding — the disclosure block is required
Every concept must carry a `grounding` line, and it must be true. This is the same rule as the Grounded Inputs corpus, surfaced to the client: state exactly what is real (which lab panel, which review, which product photography) and, by omission, what is illustrative. The source pattern's line is the model — *"Results are Truvani's actual Light Labs panel (Vanilla, tested Nov 13, 2025). Imagery is Truvani's own product & lifestyle photography."*
Never present invented stats, fabricated test results, or stock imagery as the brand's own. If a concept's proof isn't real yet, the grounding line says so ("Results shown are illustrative pending the lab panel") — a review page that launders fiction as fact is worse than no review page.
## Populating the data safely
The `DATA` lives in a `<script type="application/json" id="review-data">` block — it's inert data (parsed with `JSON.parse`), not executable code, so a value can never run as script. Two rules when you write it:
- **Valid JSON only** — double-quoted keys and strings, no comments, no trailing commas. (The page shows a clear error banner if the JSON is malformed, so a typo fails loud, not silent.)
- **Escape `<` as `\u003c` in every text value.** A value literally containing `</script>` would otherwise close the data block early. Since agents write the JSON, apply this escape mechanically to all string values. All values are HTML-escaped again at render time, so this is defense-in-depth, but the source-level escape is the one that matters — do it.
## Producing and delivering it
1. Copy `assets/creative-review-template.html` into the batch's output folder as `review.html` (e.g. `outputs/YYYY-MM-DD/review.html`).
2. Replace the `DATA` object with the real project — concepts, frames, copy, grounding. Populate `image` paths for any frames you've rendered (keep them relative to the html file so the folder stays portable).
3. Verify it renders: open it in a browser, click through every concept tab, both platform and handle toggles, and each frame in the storyboard.
4. Deliver: hand off the folder (html + `images/`), or host it. For a client link, `vercel deploy` or any static host works — it's a single page with local assets.
Keep the review page next to the markdown outputs, not instead of them: `INDEX.md` and the per-concept files remain the operator's record and the grounding audit trail; `review.html` is the approval surface built on top.
## Common mistakes
- **Too many concepts** — 2–4 tabs is a decision; 10 is a menu nobody finishes. Curate before you present.
- **Unlabeled or content-labeled frames** — label by narrative job (`The proof`), not by what's pictured (`Table screenshot`).
- **Missing or dishonest grounding** — every concept discloses what's real; illustrative proof is labeled illustrative.
- **Editing the render code** — everything is data-driven; if something won't show, it's a `DATA` field, not the JS.
- **Absolute image paths** — keep image paths relative so the output folder can be zipped, moved, or hosted intact.
@@ -0,0 +1,118 @@
# The Creative Strategy Loop
Generation (Modes 1–3) answers "make me ads." This reference answers the question that comes first: **which ads are worth making, in what order, at what production cost** — and the retro that turns each month's results into next month's plan. It's the standing operating loop of a creative strategist, run by an agent with a human deciding.
```
Signals → Concepts (evidence-ranked) → Roadmap (tiered, capacity-checked) → Briefs → [Modes 1–3 produce] → Monthly retro → back into the icebox
```
---
## Step 1: Read the Three Signals
Creative direction comes from synthesis across three independent signal sources. One source alone misleads: the account tells you what worked *among things you've tried*, customers tell you why they buy *in their words*, and organic content tells you what the audience *chooses to watch when nobody's paying*.
| Signal | What to pull | How |
|---|---|---|
| **Account performance** | Winners/losers by angle, hook, format; funnel metrics per concept (see [hook-system.md](hook-system.md) diagnostic funnel); fatigue state | `google-ads` / `meta-ads` / `linkedin-ads` / `tiktok-ads` CLIs (see Tool Integrations in SKILL.md) |
| **Customer/brand** | Verbatim pain/desire/objection language; unexpected use cases; who's *actually* buying vs. who's targeted | The Grounded Inputs corpus (`inputs/reviews/`, `inputs/comments/`), sales-call notes, support themes — per **customer-research** |
| **External organic** | What the niche watches unpaid: top organic content, its hooks, formats, vocabulary; competitor ads running long enough to be presumed working | **scraping**, the social listening tooling in **social**, ad libraries, **competitor-profiling** |
**Cadence:** a monthly deep dive (60–90 min, all three sources, feeds the monthly roadmap) plus a weekly ~20-minute refresh (what changed: new winners/losers, new review themes, anything spiking organically). Research beyond what the next decision needs is busywork — every synthesis session should end in concepts, not notes.
**Trust rule:** every insight the agent surfaces must carry its receipt — which review, which ad's metrics, which organic post. An insight without a source doesn't enter the icebox. (Same grounding rules as everything else in this skill.)
---
## Step 2: Turn Signals into Evidence-Ranked Concepts
A **concept** is one testable creative hypothesis: *segment × motivation × angle × format*, with its evidence attached. "UGC for moms" is not a concept; "new-parent insomniacs (per 40+ reviews mentioning 3am feeds) × 'quiet enough to not wake the baby' × before/after demo × POV night-shot video" is.
Rank every concept by the strongest evidence supporting it:
| Tier | Evidence | Weight |
|---|---|---|
| 1 | Your own account: a converting ad with the same angle/segment | Strongest — iterate and extend |
| 2 | Your customers verbatim: recurring review/call language | Strong — build new creative on it |
| 3 | Competitor creative running 60+ days (presumed working) | Good — adapt the angle, never the ad |
| 4 | Organic engagement in the niche (unpaid views/saves on the theme) | Moderate — validate cheaply first |
| 5 | Cross-niche pattern (worked in an adjacent category) | Weak — icebox until corroborated |
| 6 | Team hunch, no external signal | Weakest — low-fi test or drop |
Higher evidence earns roadmap *priority* — an earlier slot in the slate. Production tier is a separate call, set by validation strength, existing assets, capacity, and risk: even a tier-2 customer-language concept starts low-fidelity until it shows a funnel signal. Hunches aren't banned — they're just cheap and last.
---
## Step 3: Branch on Account State
The right creative mix depends on which of two states the account is in. Diagnose before roadmapping — a plan built for the wrong state wastes the month.
**Exploration state** — nothing (or nothing new) is working:
- Go **wide, not deep**: mostly net-new concepts across different segments and angles; keep iterations to a small minority — iterating on losers multiplies losers
- **Redefine "win" per-metric**: with no full-funnel winners, a single-metric improvement (a hold-rate lift, a CPC drop, a CVR bump) on any test is a hit worth pulling on — see the diagnostic funnel
- Iterate **only on hits**; everything else stays exploratory
- Common root causes to check while testing: the creative is boring (safe, seen-before), the message is overcomplicated, the offer/UVP is unclear, or CPMs are punishing a too-narrow audience
**Scaling state** — one or more concepts are converting profitably:
- Go **deep on the winner** while it's open: a winner-led slate of visually-distinct variations of the winning concept (same message, new execution — near-duplicates mostly cannibalize the original's reach and teach you nothing new, so variations must look meaningfully different), plus a remix lane (tonal/emotional re-executions of it) and sub-angle probes drilling *into* the winning segment; tune the split to budget, fatigue speed, and production velocity
- Keep a small exploration allocation alive even mid-scale — winners fatigue, and the next winner is rarely an iteration of the current one
- Speed matters more in this state: a scaling window is finite
---
## Step 4: The Roadmap Artifact
Maintain one living document (suggested: `roadmap.md` beside the Grounded Inputs corpus) with three horizons:
```
## Icebox — every concept, evidence tier + source attached, nothing scheduled
## This quarter — 2-4 themes chosen from the icebox (the bets), with why-now
## This month — the slate: concept | evidence tier | production tier | owner | status
```
Each monthly-slate concept gets a **production tier**:
| Tier | Cost | What it is | Use for |
|---|---|---|---|
| **T1 — Iteration** | Hours | New hook/caption/crop on an existing asset | Extending proven winners |
| **T2 — Remix** | Days | New creative from existing footage/assets/AI generation | Concepts with decent evidence or a first low-fi signal |
| **T3 — Production** | Weeks | Net-new shoot, creators, full build | Only angles with own-account proof or a prior low-fi funnel signal (fidelity ladder in [hook-system.md](hook-system.md)) |
**Capacity check — the rule that keeps roadmaps honest:** count what the team (or the AI pipeline) can produce *at quality* this month, and roadmap to that number. A 20-concept slate against 8 concepts of real capacity doesn't produce 20 ads; it produces 20 compromised ones and a burned-out team. Cut by evidence rank until the slate fits.
From the slate, generate **one brief per concept** (segment, motivation + verbatim source, angle, format, hook matrix rows, production tier, success metric) and hand each to Modes 1–3 for production.
---
## Step 5: The Monthly Creative Retro
Last step of the loop, first input of the next one. One artifact per month (suggested: `retros/YYYY-MM.md`):
```
## Winners — concept, the funnel numbers, and the WHY (which element earned it)
## Losers — concept, where in the funnel it died, hypothesis for why
## Metric wins — full-funnel losers with one strong metric (these are leads, not losses)
## Learnings — pattern-level notes → written back into the icebox as new/revised concepts
## Kills — concepts retired from the icebox, with reason
## Next slate — first draft of next month, updated evidence ranks
```
Retro rules:
- **Judge concepts, not ads.** Three executions of one concept failing says the concept is wrong; one failing says the execution was.
- **Read the funnel, not the ROAS column.** The diagnostic funnel says *what* to fix; ROAS alone says only *that* something is broken.
- **Enough data before verdicts** — respect the impression/spend thresholds in Common Mistakes and the **ads** skill's decision systems; a two-day read is a coin flip.
- **Every learning lands somewhere**: icebox update, evidence re-rank, or kill. A retro that changes nothing in the roadmap was a meeting, not a retro.
To run this loop on a schedule (retro on the 1st, weekly refresh Mondays, daily batches via Mode 3), see the creative loops in **marketing-loops**.
---
## Failure Modes
- **Roadmapping without a diagnosis** — a slate built before reading the three signals is a wish list; testing without a diagnosis isn't strategy
- **Iteration-heavy slates in exploration state** — polishing losers while the real problem (angle, offer, audience) goes untested
- **Ignoring capacity** — the plan the team can't produce at quality is a plan to produce slop
- **Evidence-free concepts jumping the queue** — the loudest stakeholder's hunch ships as a T3 shoot while tier-2 customer language sits in the icebox
- **Retro as theater** — winners celebrated, nothing re-ranked, icebox untouched
- **Scaling-state complacency** — 100% of the slate on winner variations; when the winner fatigues, the pipeline is empty
@@ -0,0 +1,115 @@
# The Hook System
The first three seconds decide whether the rest of the ad exists. Hooks are the highest-leverage unit of paid creative work — and hook *diversity* is what earns incremental learning: distinct hooks reach distinct pockets of the audience, while near-identical openings mostly re-test what you already know about the same one. This reference is a complete system for generating, diagnosing, and iterating hooks — not a list of one-liners.
Use it inside Mode 1/3 generation (hooks for new concepts), Mode 2 iteration (diagnosing why an ad underperforms), and the creative strategy loop in [creative-roadmap.md](creative-roadmap.md).
---
## A Hook Is Three Components, Not a Line
In video, the hook is the simultaneous combination of:
| Component | What it is | Job |
|---|---|---|
| **Visual action** | What is literally happening on screen in seconds 0–3 | Stop the thumb |
| **Spoken line** | The first words of VO or dialogue | Open the loop |
| **Caption text** | On-screen header/overlay text | Anchor the claim for sound-off viewers |
**The no-duplication rule:** the three components must complement, never repeat. If the VO says "I stopped paying $200/mo for my gym" while the caption reads "I stopped paying $200/mo" over a static talking head, two of the three slots are wasted. Strong hooks split the work — visual shows the cancellation email, VO says the line, caption names the alternative. When writing hooks, write all three columns explicitly; a hook spec with one column filled in is a third of a hook.
Static ads collapse this to two components (visual + headline) — the same rule applies: the headline must not caption the image.
---
## The Generation Pipeline
Work top-down; hooks written without the upstream steps read like everyone else's ads.
```
Segment → Motivation → Format → Hook (three components)
```
1. **Segment** — which specific buyer this hook addresses. Not the whole ICP: a slice with a shared situation (from the Grounded Inputs corpus: reviews, comments, sales-call language). The narrower the segment, the sharper the hook.
2. **Motivation** — the single pain, desire, or objection that moves this segment, in *their* words. Pull verbatim phrases from reviews and comments; the corpus language always outperforms marketing paraphrase.
3. **Format** — the delivery vehicle: street interview, POV selfie, screen recording, unboxing, side-by-side demo, text-on-screen static, founder-to-camera, reaction stitch. Pick the format *before* writing the line — the same motivation reads completely differently as a street-interview answer vs. a confession-to-camera.
4. **Hook** — now write the three components for this segment × motivation × format cell.
**Output as a hook matrix** so coverage is visible:
```
| # | Segment | Motivation (verbatim source) | Format | Visual action | Spoken line | Caption |
```
Generate across the matrix, not down a single column — ten hooks for ten segment×motivation cells beat thirty rewordings of one cell. This is the same angle-diversity principle as the static template library: matrix diversity is audience diversity.
---
## Hook Opening Moves
A menu of proven opening structures. Cycle through them like the static templates — don't cluster on favorites:
| Move | Shape | Watch out |
|---|---|---|
| **Curiosity gap** | Withhold the noun: "Nobody tells you what actually causes this" | Must pay off within the ad or it's clickbait that poisons CVR |
| **Bold claim** | A specific, falsifiable statement: "This replaced my entire morning routine" | Needs substantiation on screen or in the on-ramp |
| **First-person confession** | "I was doing [common thing] completely wrong" | Reads fake without lived-in detail |
| **Contrast / before-after** | Two states shown or named in the first beat | The transformation must be visually honest — see compliance notes in SKILL.md |
| **Relatability / POV** | Mirror a hyper-specific situation: "POV: it's 3pm and you're on your fourth coffee" | Specificity is the entire mechanic; generic POV is invisible |
| **Question** | Ask the exact question the buyer types into search or ChatGPT | Use their phrasing verbatim from the corpus |
| **Countdown / gamified** | A timer or on-screen challenge that promises a payoff at the end | Payoff must exist; hold-rate collapses on cheats |
| **Proof-first** | Lead with the receipt — the result screenshot, the stat, the demo money-shot | Strongest when the proof brags by itself |
---
## The Diagnostic Funnel
Each metric in the delivery funnel isolates a different component. When an ad underperforms, read the funnel to find *which part* to fix instead of scrapping the whole ad:
| Stage | Metric | If it's weak, the problem is | Fix |
|---|---|---|---|
| Stop | Thumbstop / 3-sec view rate | **Visual action** (and caption) | New visual opening; same everything else |
| Stay | Hold rate (3s → 15s / 50% view) | **The on-ramp** — what follows the hook | Rework seconds 3–15, not the hook |
| Click | CTR | Desire/offer clarity mid-ad | Sharpen the promise, CTA, or proof |
| Convert | CVR post-click | Congruence — the page doesn't continue the ad | Fix the landing page or the claim, per **cro** |
Two rules this table enforces:
- **A great thumbstop is not a great ad.** A clickbait visual that attracts the wrong viewers shows up as high thumbstop + collapsed hold/CVR. Read the whole funnel before declaring a winning hook.
- **One component per iteration.** Change the visual OR the on-ramp OR the offer framing per test cycle — matching the one-variable rule in Common Mistakes.
---
## The On-Ramp Rule
The on-ramp is seconds ~3–15: the bridge from hook to body. **A good on-ramp logically extends the hook's premise; a bad one pivots to a product pitch that abandons it.** If the hook promises "what actually causes this," the next beat must start explaining the cause — not introduce the brand story.
Corollary: **every hook test is also an on-ramp test.** Swapping a new hook onto an existing ad body usually breaks the premise-bridge; when testing hooks, re-write the on-ramp to match each one. Hold rate is the on-ramp's metric — diagnose it separately from thumbstop.
---
## Fidelity Laddering
Match production cost to evidence strength (production tiers are defined in [creative-roadmap.md](creative-roadmap.md)):
- **Hunches ship low-fidelity within a day or two:** statics, text-on-screen video, voiceover-over-b-roll, remixes of existing footage. The goal is a cheap signal on the *angle*, not a polished ad.
- **Validated angles earn high-fidelity:** creator shoots, street interviews, staged demos. Only spend production budget on hooks whose low-fi version already showed a funnel signal (even a single-metric win — a hold-rate spike on an ugly static is evidence).
Testing a hunch with an expensive shoot and testing a proven angle with a throwaway static are both mistakes — the ladder runs in one direction.
---
## Grounding Rules (inherited, non-negotiable)
Hooks inherit every grounding rule from SKILL.md: every hook cites the corpus source its motivation came from; no invented claims, stats, or testimonials; verbatim customer language over paraphrase. Additionally, mine **organic content in the niche** (top-performing TikToks/Reels/posts, via the **scraping** skill or the social listening tooling in **social**) for the audience's actual vocabulary — the words the niche uses ("GLP-1" vs. the clinical term, the slang for the pain) belong in the caption and spoken line. Organic mining is language research, not copying: take the vocabulary and the visual conventions, never a creator's specific creative.
---
## Common Failure Modes
- **Thirty rewordings of one cell** — variation without matrix coverage; diversity of segment×motivation is the point
- **Components duplicating each other** — three slots saying one thing
- **Hook tested, on-ramp inherited** — premise-bridge broken, hold rate blamed on the hook
- **Funnel read stops at thumbstop** — clickbait winners scale into CVR craters
- **Polished hunches** — high-fidelity production spent on unvalidated angles
- **Marketing-voice captions** — the corpus and the niche's organic content define the vocabulary; "revolutionary formula" appears in neither
+13 -1
View File
@@ -2,7 +2,7 @@
name: customer-research
description: When the user wants to conduct, analyze, or synthesize customer research. Use when the user mentions "customer research," "ICP research," "talk to customers," "analyze transcripts," "customer interviews," "survey analysis," "support ticket analysis," "voice of customer," "VOC," "build personas," "customer personas," "jobs to be done," "JTBD," "what do customers say," "what are customers struggling with," "Reddit mining," "G2 reviews," "review mining," "digital watering holes," "community research," "forum research," "competitor reviews," "customer sentiment," or "find out why customers churn/convert/buy." Use for both analyzing existing research assets AND gathering new research from online sources. For writing copy informed by research, see copywriting. For acting on research to improve pages, see cro.
metadata:
version: 2.0.0
version: 2.0.1
---
# Customer Research
@@ -170,6 +170,18 @@ After gathering from multiple sources, synthesize into:
## Persona Generation
### When there are no reviews yet
Early-stage products (or new categories) lack first-party review data. Don't invent personas — walk outward through proxy sources, in order:
1. **Your own differentiator** — what the product does differently defines who feels that difference most; write the hypothesis down as a hypothesis
2. **Direct competitors' reviews** — their customers describe the problem space in their words (note what's praised and what's missing)
3. **Comparable products on marketplaces** — Amazon/app-store reviews for adjacent solutions to the same job
4. **Adjacent brands sharing the audience** — what else this buyer buys; their reviews reveal the buyer's broader language and values
Personas built this way are provisional: tag each with its proxy source, and replace proxy evidence with first-party evidence as real reviews arrive.
Personas should be built from research, not invented. Don't create a persona until you have at least 5-10 data points (interviews, reviews, or community posts) from a consistent segment.
### Persona Structure
+1 -1
View File
@@ -2,7 +2,7 @@
name: marketing-loops
description: "When the user wants to set up a recurring, self-running marketing workflow — a repeatable loop an AI agent runs on a cadence (weekly, daily, on a trigger) rather than a one-off task. Also use when the user mentions 'marketing loop,' 'recurring marketing workflow,' 'automate my marketing,' 'marketing on autopilot,' 'weekly marketing review,' 'ad fatigue check,' 'content refresh loop,' 'churn watch,' 'ranking drop alert,' 'always-on marketing,' 'marketing automation workflow,' or 'run this every week.' Use this to pick, adapt, and schedule an ongoing marketing loop that orchestrates the other marketing skills. For one-off marketing ideas, see marketing-ideas. For the experimentation loop specifically, see ab-testing."
metadata:
version: 1.1.0
version: 1.2.0
---
# Marketing Loops
@@ -149,6 +149,21 @@ Loops are grouped by function. Naming follows the "The X loop" convention.
- **Output**: A dated folder of grounded static ad concepts + index, ready for human selection.
- **Input freshness (companion cadence)**: Weekly, refresh `inputs/winning-ads/` with anything that scaled and prune stale examples; monthly, refresh `inputs/reviews/` and `inputs/comments/` and re-check the voice doc. Stale inputs are this loop's failure mode — output quality tracks input freshness, not run count.
### The monthly-creative-retro loop
- **Check cadence**: Monthly (first business day, reading the prior month)
- **Acts when**: The account had meaningful creative activity last month — new concepts launched with enough delivery to judge (respect the impression/spend thresholds in `ads`). If nothing launched or nothing cleared thresholds, note that and skip.
- **Purpose**: Close the creative strategy loop — turn last month's results into next month's evidence-ranked slate, so the roadmap learns instead of drifting.
- **Skills used**: `ad-creative` (Mode 4 + creative-roadmap reference), `ads` (decision thresholds), `analytics`
- **Loop body**:
1. Pull last month's ad performance via the platform CLIs; map results to the month's roadmap concepts.
2. Draft the retro artifact (`retros/YYYY-MM.md`): winners with the why, losers with funnel-stage diagnosis, single-metric wins, learnings, kills.
3. Update the roadmap: re-rank icebox evidence, write learnings in as new/revised concepts, draft next month's capacity-checked slate.
4. Flag the account-state call (exploration vs. scaling) for human confirmation — the mix recommendation depends on it.
- **Self-check**: Are verdicts on concepts (not single executions)? Did every learning land somewhere — icebox update, re-rank, or kill? Did anything clear thresholds, or is this month a skip?
- **State / idempotency**: One retro per month — skip if `retros/YYYY-MM.md` exists. The roadmap file is the shared state; never fork it.
- **Stop / bail-out**: Stages analysis and a draft slate only — the human approves the slate and the account-state call; the loop **never launches or pauses ads**. If retros go unread for two cycles, pause and ask.
- **Output**: The monthly retro artifact + an updated roadmap with a draft slate for the coming month.
### The paid-search query-mining loop
- **Check cadence**: Weekly
- **Acts when**: Search-term reports reveal wasted spend or new intent.