@stacksjs/defaults 0.75.109 → 0.75.111

package/ai/skills/stacks-marketing-ad-creative/evals/evals.json

@@ -0,0 +1,280 @@
+{
+  "skill_name": "stacks-marketing-ad-creative",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Generate ad creative for our Meta (Facebook/Instagram) campaign. We sell an AI writing assistant for content marketers. Main value prop: write blog posts 5x faster. Target audience: content marketing managers at B2B SaaS companies. Budget: $5k/month.",
+      "expected_output": "Should check for product-marketing.md first. Should generate creative following the angle-based approach: identify 3-5 angles (speed, quality, ROI, pain of blank page, competitive edge). For each angle, should generate primary text (≤125 chars), headline (≤40 chars), and description (≤30 chars) respecting Meta character limits. Should provide multiple variations per angle. Should suggest image/visual direction for each. Should organize output with angle name, hook, body, CTA for each variation. Should recommend which angles to test first.",
+      "assertions": [
+        "Checks for product-marketing.md",
+        "Uses angle-based generation approach",
+        "Identifies multiple angles (3-5)",
+        "Respects Meta character limits (125/40/30)",
+        "Generates multiple variations per angle",
+        "Suggests image or visual direction",
+        "Includes hook, body, and CTA for each",
+        "Recommends which angles to test first"
+      ],
+      "files": []
+    },
+    {
+      "id": 2,
+      "prompt": "I need Google Ads copy for our CRM product. We're targeting the keyword 'best CRM for small business'. Need responsive search ads.",
+      "expected_output": "Should generate Google RSA creative respecting character limits: headlines (≤30 chars each, need 10-15 variations) and descriptions (≤90 chars each, need 4+ variations). Should note that pinning should be used sparingly as it reduces optimization. Should include the target keyword in headlines. Should provide multiple angle-based variations. Should suggest ad extensions (sitelinks, callouts, structured snippets). Should follow Google Ads best practices for RSA.",
+      "assertions": [
+        "Respects Google RSA character limits (30 char headlines, 90 char descriptions)",
+        "Generates 10-15 headline variations",
+        "Generates 4+ description variations",
+        "Includes target keyword in headlines",
+        "Notes pinning should be used sparingly per skill guidance",
+        "Suggests ad extensions",
+        "Uses angle-based variation approach"
+      ],
+      "files": []
+    },
+    {
+      "id": 3,
+      "prompt": "Here's our ad performance data: Ad A (pain point angle) - CTR 2.1%, CPC $3.20, Conv rate 4.5%. Ad B (social proof angle) - CTR 1.4%, CPC $4.10, Conv rate 6.2%. Ad C (feature angle) - CTR 0.8%, CPC $5.50, Conv rate 2.1%. Help me iterate on these.",
+      "expected_output": "Should activate the iteration-from-performance mode (not generate-from-scratch). Should analyze the data: Ad A has best CTR, Ad B has best conversion rate (highest efficiency despite lower CTR), Ad C is underperforming on all metrics. Should recommend doubling down on the pain point angle (high CTR) and social proof angle (high conversion), while pausing or reworking the feature angle. Should generate new variations that combine winning elements (pain point hook + social proof). Should suggest specific iterations on Ad A and Ad B.",
+      "assertions": [
+        "Activates iteration mode based on performance data",
+        "Analyzes CTR, CPC, and conversion rate for each ad",
+        "Identifies winning angles from the data",
+        "Recommends pausing or reworking underperforming creative",
+        "Generates new variations combining winning elements",
+        "Provides specific iterations on top performers"
+      ],
+      "files": []
+    },
+    {
+      "id": 4,
+      "prompt": "we need linkedin ads for our enterprise security product. audience is CISOs and IT directors.",
+      "expected_output": "Should trigger on casual phrasing. Should generate LinkedIn ad creative respecting character limits: introductory text (≤150 chars), headline (≤70 chars), description (≤100 chars). Should adapt tone and messaging for enterprise security audience (CISOs, IT directors) - more formal, compliance-focused, risk-reduction language. Should provide multiple angles relevant to security buyers (risk reduction, compliance, incident response time, cost of breaches). Should suggest ad format recommendations for LinkedIn (sponsored content, message ads, etc.).",
+      "assertions": [
+        "Triggers on casual phrasing",
+        "Respects LinkedIn character limits (150/70/100)",
+        "Adapts tone for enterprise security audience",
+        "Uses risk-reduction and compliance language",
+        "Provides multiple angles relevant to security buyers",
+        "Suggests LinkedIn ad format recommendations"
+      ],
+      "files": []
+    },
+    {
+      "id": 5,
+      "prompt": "I need to generate a big batch of ad variations for a multi-platform campaign launching next week. We're a meal delivery service targeting busy professionals. Need ads for Google, Meta, and TikTok.",
+      "expected_output": "Should activate the batch generation workflow. Should generate creative for all three platforms respecting each platform's character limits: Google RSA (30/90), Meta (125/40/30), TikTok (80 chars recommended, 100 max). Should identify 3-5 angles that work across platforms (convenience, health, time savings, variety, cost vs eating out). Should generate variations per angle per platform. Should note platform-specific creative considerations (TikTok needs video concepts, not just text). Should organize output clearly by platform.",
+      "assertions": [
+        "Activates batch generation workflow",
+        "Generates for all three platforms",
+        "Respects each platform's character limits",
+        "Identifies angles that work across platforms",
+        "Notes TikTok needs video concepts",
+        "Organizes output by platform",
+        "Generates multiple variations per angle per platform"
+      ],
+      "files": []
+    },
+    {
+      "id": 6,
+      "prompt": "Help me plan our overall paid advertising strategy. We have a $20k monthly budget and want to figure out which platforms to use and how to allocate spend.",
+      "expected_output": "Should recognize this is a paid advertising strategy task, not ad creative generation. Should defer to or cross-reference the ads skill, which handles campaign strategy, platform selection, and budget allocation. May briefly mention creative considerations but should make clear that ads is the right skill for strategy.",
+      "assertions": [
+        "Recognizes this as paid ads strategy, not creative generation",
+        "References or defers to ads skill",
+        "Does not attempt full campaign strategy using creative generation patterns"
+      ],
+      "files": []
+    },
+    {
+      "id": 7,
+      "prompt": "I want to make one of those iMessage-style video ads for Meta - the ones where a fake text conversation reveals the product and a promo code. We sell a sleep tracking ring. Our promo code is RESTED.",
+      "expected_output": "Should load references/imessage-video-ads.md. Should start by picking a concept angle from the six-angle catalog (result-as-screenshot, setup flex, cancellation moment, feature-as-punchline, friend-asks-friend inverse, receipt-as-hook) before writing bubbles - likely result-as-screenshot (a sleep score) for this product. Should draft an 8-14 bubble script in real texting voice where the brand appears only after the peer asks, with the RESTED code delivered conversationally inside a bubble and repeated on a static end card. Should apply grounding rules: any sleep-improvement claim in the thread must trace to a real customer result or product fact, and the thread must not be framed as a real testimonial. Should present production route options (a code-based Playwright+ffmpeg pipeline, or Remotion) rather than assuming one, and mention key craft rules (the recognizable send/receive SFX, silent typing indicators, 9:16 1080x1920).",
+      "assertions": [
+        "Loads or applies the imessage-video-ads reference",
+        "Selects a concept angle before writing the script",
+        "Script is 8-14 bubbles in authentic texting voice",
+        "Brand name appears only after the peer asks about it",
+        "Promo code RESTED appears in a bubble and on the end card",
+        "Applies grounding rules - no fabricated claims, not framed as a real testimonial",
+        "Mentions at least one production route and key craft rules (SFX, silent typing indicator, 9:16)"
+      ],
+      "files": []
+    },
+    {
+      "id": 8,
+      "prompt": "We sell a menopause supplement. I saw those ads where someone asks ChatGPT a health question and the answer recommends the product - make one of those for us. Also curious about the Apple Notes version.",
+      "expected_output": "Should load references/imessage-video-ads.md and apply the Other iOS-Native Reveal Surfaces section. Should flag the compliance constraint prominently BEFORE drafting: a fabricated AI answer making health claims is the highest-risk version of this format - every claim needs substantiation, health/medical advice in a fake ChatGPT answer needs legal review, and the exchange must not be presented as a real unprompted ChatGPT output endorsing the product. May propose a compliant angle (mechanism education grounded in documented facts) or steer to the Apple Notes confession format as the lower-risk fit for a transformation story. For the Notes version: title-as-hook, first-person list with the product as the least enthusiastic line, keyboard-taps-only audio, grounding realizations in real reviews. Should apply surface-selection guidance rather than treating the three formats as interchangeable.",
+      "assertions": [
+        "Applies the iOS-native reveal surfaces section of the imessage-video-ads reference",
+        "Flags health-claim/substantiation risk for the fabricated ChatGPT answer before or while drafting",
+        "Does not present the ChatGPT exchange as a real unprompted output endorsing the product",
+        "Recommends legal review or a compliant reframe for health advice in the AI answer",
+        "Apple Notes guidance: title-as-hook, first-person confession, product as an understated list item, keyboard-taps-only audio",
+        "Grounds claims and realizations in documented facts/reviews (Grounded Inputs)",
+        "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": []
+    },
+    {
+      "id": 11,
+      "prompt": "I want to make one of those AirDrop-style video ads - where a phone gets an incoming AirDrop and you tap accept. We sell a limited-run sneaker drop.",
+      "expected_output": "Should apply the AirDrop surface in references/imessage-video-ads.md (the iOS-native reveal family), not treat it as a novel format. Should build the ad around the interaction: an incoming AirDrop card (translucent sheet, sender device name, a preview thumbnail, gray Decline / blue Accept) from the receiver's POV, with the Accept tap as the reveal beat and the transfer progress-ring as the signature motion. Should make the preview thumbnail earn the tap (the sneaker money-shot / the drop), cast a relatable human sender name rather than the brand, use the AirDrop swoosh sound (not iMessage tritones) with the Apple trade-dress note, and keep it short. Should apply the family grounding/disclosure rules (a dramatization of a share, not a real endorsement; claims substantiated). May note receiver-POV-by-default vs sender-POV-as-flex.",
+      "assertions": [
+        "Applies the AirDrop iOS-native-reveal surface, not a from-scratch format",
+        "Builds around the incoming-AirDrop-card + accept-tap-as-reveal interaction (receiver POV)",
+        "Preview thumbnail is treated as the hook that must earn the accept",
+        "Casts a relatable human sender name, not the brand, on the incoming card",
+        "Uses the AirDrop swoosh sound + Apple trade-dress note, not iMessage tritones",
+        "Applies the family grounding/disclosure rules (dramatized share, substantiated claims, not a real endorsement)"
+      ],
+      "files": []
+    },
+    {
+      "id": 12,
+      "prompt": "We're a mobile app and want to make TikTok/Reels ads. Give me a UGC reaction ad concept and make sure it won't get cut off by the app UI. Also - should we add music?",
+      "expected_output": "Should load references/short-form-video-specs.md and deliver both the format and the spec. Format: the Reaction + Demo hard-cut structure (creator reaction ~3s with a hook caption written as inner monologue, hard cut to the app demo, optional payoff caption) - may also mention the other two creator formats (no-yapping split-screen, greenscreen reaction) as alternatives. Safe zone: keep all captions/key visuals inside the 720x1200 centered safe band (220px top / 500px bottom / 180px sides clear) so platform UI doesn't cover them, and use the static white-fill/black-stroke caption style that auto-sizes to fit. Music: give the organic-vs-baked decision - for organic posting, export without baked music and attach the trending sound in-app (algorithm reward); bake music only for paid ads or where native sound can't be attached, fading out the last ~0.8s.",
+      "assertions": [
+        "Provides the reaction+demo hard-cut structure with the hook caption as the reaction's inner monologue",
+        "Specifies the cross-platform safe band (roughly 220 top / 500 bottom / 180 sides, or the 720x1200 text-safe area) so captions aren't covered by platform UI",
+        "Describes the static white-fill/black-stroke caption style with auto-sizing (no animated captions)",
+        "Gives the organic-vs-baked-music decision rather than a blanket yes/no (attach trending sound in-app for organic; bake for ads)"
+      ],
+      "files": []
+    },
+    {
+      "id": 13,
+      "prompt": "We're a DTC brand with a stalled Meta account and need fresh static ad concepts that can actually open cold net-new audiences - not just retarget. Which static templates should we lead with, and which should we avoid right now? Also, we have several SKUs.",
+      "expected_output": "Should load references/static-ad-templates.md and reason from the tier + funnel-role tagging rather than treating all templates as interchangeable. For cold net-new reach, should prioritize the S/A-tier statics - Founder Message and Origin Story (S, founder content is the reliable first cold-scaler) and, because the brand has multiple SKUs, the Grid Static (A, multi-SKU/bundle, low-hanging fruit that scales cold). Should explain the unicorn-scaler-vs-supporting-cast lens: most B-tier templates (Us vs. Them, Before/After, FAQ Card, Callout) convert mid-funnel and shouldn't be expected to open cold reach or be killed for failing to. Should flag the decayed formats to avoid: Press Mention (F - rights nightmare), Testimonial statics (E - unless golden-nugget), Numbered List/Listicle (E - dead lately). Should keep grounding rules (concepts trace to real reviews/winning ads/comments; no fabricated social proof). May cross-reference the fuller format map for video/partnership formats.",
+      "assertions": [
+        "Loads or applies the static-ad-templates reference and reasons from tier + funnel role",
+        "Prioritizes S/A-tier statics for cold reach (Founder Message, Origin Story, Grid Static)",
+        "Recommends the Grid Static specifically given multiple SKUs",
+        "Explains the unicorn-scaler vs. supporting-cast lens (B-tier = mid-funnel, don't kill for failing to scale cold)",
+        "Flags decayed formats to avoid (Press Mention F, Testimonial statics E, Listicle/Numbered List E)",
+        "Preserves grounding rules - no fabricated social proof"
+      ],
+      "files": []
+    },
+    {
+      "id": 14,
+      "prompt": "We're a DTC supplement brand and our Meta reach has been flat for weeks. We can make basically any ad. What creative format should we make next, and what should we NOT waste time on?",
+      "expected_output": "Should load references/meta-creative-formats.md and answer as a which-format-to-make-next decision, not a from-scratch copy dump. Should lead with the unicorn-scaler vs. supporting-cast lens and the persona-based Andromeda context (creator-fronted formats reach personas natively), and tie the flat/declining reach specifically to deploying creator-fronted formats - especially partnership ads (the #1 priority) - to restore net-new reach. Should surface the S-tier picks (founder content as the reliable first winner, partnership ads, VSL for education-heavy niches like supplements) and relevant A-tier options (authority ads fit a supplement brand, grid statics as low-hanging fruit). Should explicitly de-prioritize F-tier (press ads, podcast ads unless a founder is on a known show, notes-app/UX fake-native ads that 'do not convert' and confuse the algorithm). Should frame the answer as building a portfolio (scalers + supporting cast), and route to the static/video references for how to actually build the chosen format.",
+      "assertions": [
+        "Loads or applies the meta-creative-formats reference",
+        "Frames the answer with the unicorn-scaler vs. supporting-cast distinction",
+        "Explains the persona-based Andromeda reason creator-fronted formats rank highest",
+        "Ties flat/declining reach to deploying partnership ads (the #1 priority) to restore net-new reach",
+        "Recommends S-tier picks (founder content, partnership ads, VSL) and a fitting A-tier option (authority ads and/or grid statics)",
+        "Explicitly de-prioritizes F-tier (press, podcast-unless-known-show, notes-app/UX fake-native)",
+        "Frames it as building a portfolio and routes to static/video references for production"
+      ],
+      "files": []
+    },
+    {
+      "id": 15,
+      "prompt": "We're a health supplement brand and want video ads that will actually scale to cold audiences, not just retarget. What creator formats should we prioritize, and can our founder be in them?",
+      "expected_output": "Should load references/short-form-video-specs.md and reason from the scale-vs-support tier logic, not list formats flatly. For scaling cold in a trust-gated health niche it should prioritize the higher-tier creator-fronted formats - VSL (S; upfront education, the mechanism-then-offer script) and Authority (A; a credentialed expert, with the caveat that health claims must be real/substantiated and routed through legal review per Grounded Inputs) - and can also point to Yapper, Amateur Investigation, and David & Goliath (all A) as cold-scaling options. Founder: yes - founder's content is often a brand's first top performer, and the founder can carry a Yapper or David & Goliath via the founder/organic-vlog structures (hero's journey, math, shiny-object, niche-guide). Should mention the practical production system (three-capture close/medium/wide shooting, 0.5-1s cut formula) and frame the answer as building a portfolio across tiers rather than betting on one format.",
+      "assertions": [
+        "Reasons from the scale-vs-support tier logic (prioritizes higher-tier cold-scaling formats over a flat list)",
+        "Recommends VSL and/or Authority for the education-heavy, trust-gated health niche, and flags the health-claims/legal-review compliance caveat for the Authority/expert format",
+        "Confirms the founder can front the ads (founder content as a common first top performer) via a founder/organic-vlog structure such as hero's journey or David & Goliath",
+        "References the founder shooting/edit system (three-capture close/medium/wide and/or the 0.5-1s cut formula) and/or framing the mix as a portfolio across tiers"
+      ],
+      "files": []
+    },
+    {
+      "prompt": "Give me 10 Meta ad primary-text variations for our no-code website builder. It needs no developer, no hosting setup, and no credit card to start.",
+      "expected_output": "Should write 10 variations that avoid AI tells even though the brief is a list of absences. Should not stack negations ('No developer. No hosting. No card.') in any variation; may state one absence plainly. No contrast reveals, self-answered questions, colon reveals, em dashes, or stock phrases ('Say goodbye to', 'Unlock'). No two variations should share the same sentence shape, and hooks should be specific rather than 'POV:' or 'Stop scrolling'.",
+      "assertions": [
+        "No variation stacks three negations",
+        "No contrast reveals or self-answered questions",
+        "No em dashes",
+        "Variations don't repeat the same sentence shape",
+        "No 'POV:' / 'Stop scrolling' / stock-phrase hooks"
+      ],
+      "files": [],
+      "id": 16
+    },
+    {
+      "id": 17,
+      "prompt": "We sell forecasting software. Problem-aware finance teams spend Friday comparing CSV exports. Product facts: imports CSVs into one approval queue; no quantified time study. Customer notes: R1 says “three versions of the final spreadsheet”; R2 says “I want Friday to end with a finished forecast.” Existing ad A uses R1 and gets clicks but few qualified demos. Create three text-led LinkedIn static concepts and a mobile visual brief.",
+      "expected_output": "Applies awareness-headline reference; distinct grounded treatments with R1/R2/product evidence, no fabricated hours/statistics. Specifies headline-dominant composition and actual mobile readability including qualifiers, not invented LinkedIn policy. Diagnoses qualified-demo continuity rather than calling CTR a win.",
+      "assertions": [
+        "Uses a stated problem-aware audience assumption",
+        "Produces distinct grounded concepts with source IDs",
+        "Does not invent quantified time-saving or fake customer dialogue",
+        "Includes actual-size mobile headline/qualification readability check",
+        "Connects success to qualified demos rather than clicks alone"
+      ],
+      "files": []
+    },
+    {
+      "id": 18,
+      "prompt": "Our meal delivery service has two customer comments: C1 “I am still on the train when my kids ask about dinner,” C2 “Sunday grocery planning starts over every week.” Product fact F1: one order supplies three dinners. Make cold-audience static ideas using conversation and a stat callout. Can you make up three more quotes so we have five?",
+      "expected_output": "Uses supplied language and fact with unfamiliar/problem-aware assumptions; declines invented customer quotes and reports limited corpus. A invented exchange if used is explicitly dramatization without fake attribution; three-dinner quantity traceable to F1. Provides truthful legible layouts.",
+      "assertions": [
+        "Reports two available customer phrases rather than inventing five",
+        "Labels invented dialogue as dramatization or uses permitted actual wording",
+        "Traces quantity to F1",
+        "Distinguishes awareness hypotheses and supplies mobile visual direction"
+      ],
+      "files": []
+    },
+    {
+      "id": 19,
+      "prompt": "We have a pilot summary: 8 SaaS teams, March, weekly reconciliation median fell from 6 hours to 2; no independent control. Make a headline creative saying every customer saves 67%, with a tiny footnote. We also want to shame buyers still using spreadsheets.",
+      "expected_output": "Keeps result scoped to pilot median/sample/period, declines universal causal guarantee and buyer shaming. A headline with meaningful legible adjacent qualifiers or a safer non-stat alternative; qualified copy cannot be hidden in tiny text. Preserves truthful precision rather than changing number to seem real.",
+      "assertions": [
+        "Does not generalize pilot to every customer or causal guarantee",
+        "Keeps sample/period/median scope available in readable qualification",
+        "Rejects shrinking material qualification into an unreadable footnote",
+        "Critiques workflow without shaming buyers",
+        "Does not claim round numbers are fake"
+      ],
+      "files": []
+    },
+    {
+      "id": 20,
+      "prompt": "Give me six headline concepts for our product. No product description, audience, customer language, proof, platform, or offer is available. Can you just fill every formula with made-up results?",
+      "expected_output": "Requests the key missing context and evidence instead of manufactured claims; may explain treatments as hypothetical structure, but not ready-to-run ungrounded product ads. Does not force six outputs from an empty corpus.",
+      "assertions": [
+        "Asks for missing product/audience/evidence/placement context",
+        "Does not fabricate results or testimonials",
+        "Keeps illustrative formulas distinct from deliverable ads",
+        "Does not promise formula choice proves conversion"
+      ],
+      "files": []
+    }
+  ]
+}

package/ai/skills/stacks-marketing-ad-creative/references/awareness-headlines.md

@@ -0,0 +1,54 @@
+# Awareness-Based Headline Creative
+
+Use for text-led static concepts, especially B2B feed ads. These are compact treatments within the existing angle and template workflow; they do not replace audience research, the hook system, or platform specs.
+
+Concept lineage: the maintainer's #404 follow-up to the ivangfalco/ads-skills remix. Re-expressed independently and reconciled with this repo's grounding and AI-tells rules; no source copy or creative assets imported.
+
+## Choose the Reader's Next Step
+
+| Awareness | What the reader needs | Useful treatments | CTA direction |
+|---|---|---|---|
+| Unaware / unfamiliar with the category | Recognize a specific lived situation | Feeling, conversation | Learn about the situation or mechanism |
+| Problem-aware | See a credible path out of a named friction | Pain + outcome, time-anchored friction | See the workflow or explanation |
+| Solution-aware | Understand a concrete way this approach differs | State change, documented statistic | Compare the mechanism or watch a demo |
+| Product-aware | Resolve an objection with specific proof | Statistic, pain + outcome | Inspect proof, try, or book the relevant next step |
+
+Stage is a working hypothesis about this audience, not a diagnosis based on the platform alone. If unknown, state the assumption and propose two distinct stage hypotheses. A formula alone cannot prove an ad will convert.
+
+## Six Treatments
+
+The examples below are invented illustrations of structure, **not** approved product claims, real customer quotes, or ready-to-run ads. Replace their facts with the user's verified corpus. Each treatment can serve multiple stages; choose based on what the reader already knows.
+
+| Treatment | Construction and guardrail | Illustrative SaaS example | Illustrative DTC example |
+|---|---|---|---|
+| **Feeling** | Name a recognizable feeling tied to a specific work/life moment. Avoid vague empowerment or a forced positive/negative reveal. | “Leave Friday with the forecast finished.” | “Dinner sorted before the commute home.” |
+| **Conversation** | Two short lines from a recognizable situation. Use an actual permitted exchange, or label invented dialogue as a dramatization; never fabricate testimonial attribution. | “Is this the final sheet?” / “There are three final sheets.” | “What's for dinner?” / “I'm still on the train.” |
+| **State change** | Show the current and proposed workflow with concrete artifacts. State what changes; don't force “not X, Y” copy or unsupported competitor claims. | “Bring the three approval threads into one queue.” | “Pack tomorrow's lunch while tonight's dinner cooks.” |
+| **Time-anchored friction** | Name an obsolete or repetitive process and its actual moment. Critique the process without shaming the buyer or inventing a trend. | “Month-end still starts with copying CSVs.” | “The Sunday grocery list starts over again.” |
+| **Documented statistic** | One supported number plus the population, period, or meaningful qualifier. Keep its real precision; rounded numbers are not evidence of fakery. | “Pilot teams cut weekly reconciliation from 6 hours to 2.” | “Three dinners packed in one delivery.” |
+| **Pain + outcome** | One named friction and a concrete next action/outcome, usually under ten words. Brevity is a draft constraint, not permission to drop a material qualifier. | “Find the missing invoice before close.” | “Get dinner ready between calls.” |
+
+Read each draft against the existing AI-tells guidance. Do not produce six near-identical sentences just to fill a formula menu. Preserve customer language where it is permitted and relevant; facts can ground a paraphrase without becoming a fabricated quote.
+
+## Gather Proof Before Copy
+
+Build a small evidence sheet: source ID, verbatim phrase or product fact, audience, date, allowed usage, and limitations. Aim for five useful customer phrases when available, across more than one perspective. If the available corpus is smaller, report the gap and reduce diversity claims; do not invent quotes to meet a count. Existing Grounded Inputs requirements still apply to scaled Mode 3 batches.
+
+Separate **language evidence** (“the export takes forever”) from **claim evidence** (a measured reduction across a defined pilot). A complaint supports the pain angle; it does not substantiate a numerical performance promise. Preserve a pilot's sample size and period in adjacent readable copy or withhold the statistical concept when a truthful presentation cannot fit.
+
+## Make the Headline the Visual
+
+Apply this treatment to Headline Statement or Stat Callout from the static library when the words carry the concept. It is a production hypothesis, not a guarantee that text-only ads beat every other format.
+
+- Start with one dominant sentence and a bold, legible sans-serif face. As a design starting point, let the headline occupy roughly 50-70% of the composition; adjust after actual-size testing.
+- Use intentional line breaks that keep phrases together. Keep the product/logo secondary unless recognizing the product is the concept's job.
+- Test a dark background with light text, or a strong brand-colored background with contrasting text. Choose from the user's actual palette and verify readability; avoid a color prescription based on an unverified feed theme.
+- Include the audience's specific moment, one defensible idea, and enough qualification to read truthfully. Exclude stock imagery competing with the sentence, tiny disclaimers, fake review UI, extra badges, and an unsupported second claim.
+- Make a preview at the **actual mobile feed display size**, not only on a desktop canvas. Check that a reviewer can read the entire headline and its material qualifiers without zooming. If not, shorten the claim or change the layout; never solve it by shrinking required qualifications.
+- Get current export dimensions, cropping, safe areas, and text-field limits from the platform-spec reference and the selected placement. The 50-70% layout suggestion is not a platform rule or a text-coverage approval threshold.
+
+## Deliver and Learn
+
+For each concept, provide: audience/stage assumption, distinct angle, treatment + static template, headline, supporting qualification, CTA, source IDs, and visual specification with mobile-readability check. Mark evidence gaps and keep output as concepts for review unless publication is already authorized.
+
+Test stage/angle hypotheses before fine font changes. Compare the relevant downstream qualified outcome with the existing control, keeping offer and audience stable where possible. Strong CTR with weak qualified conversion is a reason to examine the promise and landing-page continuity, not proof of a winning headline.

package/ai/skills/stacks-marketing-ad-creative/references/creative-review-page.md

@@ -0,0 +1,109 @@
+# 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 - local path/file URL 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.",
+      likes: "6,240",                       // optional - Instagram like count; omit and no count is shown
+      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 **stacks-marketing-social** skill and pick the arc that fits the angle before writing frames.
+
+### Images vs. placeholders
+
+Every frame renders one of two ways:
+- **`stacks-marketing-image` provided** - the real creative (from the Mode 3 `images/` folder or a data URI) fills the frame.
+- **`stacks-marketing-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.
+
+Remote and protocol-relative image URLs are blocked, including URL spellings the browser normalizes. Download authorized creative assets into the local `images/` folder and keep paths relative when hosting or sharing; hosted relative assets still load from that host. This restriction applies to the supplied image sources, not a sandbox for arbitrary edits to the HTML or an assurance about a hosting server.
+
+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 `stacks-marketing-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.

package/ai/skills/stacks-marketing-ad-creative/references/creative-roadmap.md

@@ -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 **stacks-marketing-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 **stacks-marketing-social**, ad libraries, **stacks-marketing-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 **stacks-marketing-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 **stacks-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