B-Roll Finder

B-Roll Finder — skill methodology

A reusable methodology for sourcing and placing b-roll on talking-head video. Genericized from a working agent skill. Adapt paths and brand tokens to your own setup.

⛔ USER OVERRIDES ARE LAW — and they persist

When the user states a preference or ban mid-run ("no memes", "no text cards", "nothing political"), it applies IMMEDIATELY and for the rest of the session, AND gets written into the profile's Guardrails right then — not at the end. A banned category is never sourced again, never proposed again, never "just one candidate to check". Violating a stated ban is the worst failure this skill can make: it tells the user the agent doesn't listen.

⛔ STEP 0 — ONBOARDING GATE (run this check before ANYTHING else, every session)

Open the profile (TASTE.md or the user's fork). The ONLY thing that skips onboarding is a literal Confirmed-by: <name> (<date>) line at the top of the profile. No line → ask the four onboarding questions (below) out loud, write the answers into the profile, add the line. This is NOT optional and NOT inferable:

• Do NOT infer the answers from CLAUDE.md, memory, prior conversations, or this profile's prose — even if you are confident you know them. Asking IS the feature.
• The shipped TASTE.md is an EXAMPLE, even if the current user is its original author. Author ≠ confirmed.
• A CLAUDE.md pointer that says "load my taste profile" does not count as confirmation either — check for the line.
• "redo my profile" re-triggers onboarding at any time.

The one rule that governs everything

The agent NEVER picks the final b-roll. The user does. The right clip is often a taste call. This skill's job is to narrow the funnel — classify each moment, scope the search to trusted/authoritative sources, score candidates, and hand back a tight contact sheet. The user makes the final pick.

The taste profile — load it before sourcing anything

Curation is half the skill. Every run starts by loading a taste profile: the b-roll fingerprint (which types, how fast to cut), the trusted-source list tagged by topic, and the guardrails. This repo ships with a working default — TASTE.md, revealed from real published videos — so the skill has good taste out of the box. Use it as-is until the user builds their own (TASTE.md's "Make it yours" section covers the import-then-prune mechanism: pull their YouTube subscriptions via yt-dlp --cookies-from-browser, prune together, then reveal their fingerprint from their own published videos).

Onboarding preferences (ask once, store in the profile)

When onboarding fires: the shipped TASTE.md is an EXAMPLE profile (the author's), not the user's. On first run, check the profile for a Confirmed-by: line naming the current user. Absent → run onboarding: ask the questions below, write the answers into the user's profile (their fork of TASTE.md), and add Confirmed-by: <user> (<date>) at the top. Present → skip onboarding and just load it. The user can re-trigger anytime with "redo my profile".

Ask these on first run and write the answers into the taste profile (TASTE.md ships with one set of answers; confirm they fit):

1. Audio — does the user talk over b-roll (strip ALL audio: ffmpeg -an) or want the clip's sound?
2. Stills motion — static images get a very subtle Ken Burns zoom-in by default (~1.5%/sec, centered, capped ~2%/sec); offer opt-out to fully static. Method matters more than the setting — see "Stills motion" below.
3. Source attribution — credit each b-roll's source in small text bottom-right? Options: off · white · black · auto (contrast-pick per clip). The credit is the source's canonical name + platform ("Vinexposium / YouTube", "Decanter") — short, never a URL. If the footage already carries its own badge bottom-right, move the credit bottom-left for that clip. Note: an on-screen credit is etiquette, not a license — official/authoritative sources remain the real copyright posture.
4. Concept motion graphics (Remotion) — generate on-brand motion graphics for concept/stat/chart beats? If yes, ask for the path to an EXISTING Remotion project (+ brand tokens) and write it into the profile. Rendering a comp in an existing project is part of the lean path; scaffolding a new project is a one-time setup step that needs explicit permission (never mid-run). No project + no permission → concept beats use real authoritative footage or get flagged, never silently skipped.
5. AI-generated b-roll — off by default; opt-in only for beats with no real footage, via a quality model the user names. Never silently substitute cheap AI stock.

🔓 Standing authorization — invoking the skill IS the permission

Do NOT ask conversational permission for access or searches while sourcing — running /find-broll already authorizes the skill to act on the user's behalf. Never ask "want me to search/look up/access X?" for:

• Web searches, news/headline lookups, oEmbed/embed endpoints
• yt-dlp metadata searches and downloads of public videos/channels
• Headless-browser captures of public pages (incl. clicking through cookie/consent walls)
• The user's logged-in browser or browser cookies for sourcing/reading (profiles, posts, walled pages)
• Reading local files, transcripts, prior project folders, the user's asset library

Just do it and show the result. The user's taste checkpoints stay: the plan approval before sourcing and the final pick on taste-route beats. The ONLY things that still warrant a question: publishing/posting anything outward, paid actions, deleting user files, and installing heavy dependencies. Ask-permission friction everywhere else is a bug, not politeness.

⚡ LEAN PATH IS THE DEFAULT — the funnel is for taste calls, not everything

The skill earned trust through restraint; heavyweight process makes output WORSE, not better (tested 2026-06-11: a full-funnel run took ~10× longer and shipped worse composition than the lean run). Defaults:

• Plan approval IS the pick. When the user approves the beat plan ("go for it"), source ONE best candidate per beat for objective routes (Entity/Receipts/Product) and place it. NO multi-candidate sourcing, NO contact sheets. (Contact sheets exist only when the user EXPLICITLY asks for options on a beat — and meme/cultural beats are never auto-sourced at all; see the routing table.)
• Research depth is bounded at plan time. Verify referents enough to source accurately; do NOT exhaust every sourcing route before the plan. The escalation ladder fires only AFTER the user has agreed a beat and the easy routes failed — never speculatively.
• Per-beat time box: if a single beat's sourcing exceeds ~5 minutes, place the best-available candidate or drop the beat and flag it. One stubborn artifact must not stall the edit.
• One verify pass + targeted fixes beats endless polishing. Render → grid → fix the failures → re-verify only the fixed beats.
• NO RETRIES — first failure switches, second failure drops. A method that fails once is NOT retried (not with tweaked flags, not "one more time") — switch to a different method immediately. If the second method also fails, DROP the beat, flag it in the plan, move on. A beat is never worth a third attempt; the edit ships without it. This applies to everything: captures, downloads, renders, browser actions. (Louise: "stop doing things that keep failing, just skip to save time.")
• Never auto-install heavy dependencies mid-run (conda, aligners, etc.) — use the fallback, note it, offer the install after delivery.

Source by SOURCE, not by beat (the big sourcing speed-up)

After the plan is approved, cluster beats by where their asset lives, then fetch each source ONCE:

• One full-page capture of the subject's website often covers 4–6 beats (history, team photo, map, packshots) — crop per beat from the same capture.
• One official channel/film often covers several beats (an aerial, a close-up, a process shot) — download once, cut multiple windows.
• Run all downloads as ONE batched background job (metadata-only search first, download only the chosen items); run captures as a second batch in parallel. Never fetch serially beat-by-beat.
• Cache raw downloads next to the project (assets/raw/) so re-renders and v2s never re-fetch.

Accuracy over volume

Fewer, perfectly-accurate beats beat lots of mediocre ones. The habit to kill is keyword-matching to hit a quota.

• Every beat passes a per-citation interpretation — write "what is this line actually about?" first, then source THAT. If you can't source something that accurately illustrates the real point, drop the beat — don't pad. No b-roll is better than wrong b-roll.
• Default cadence = front-loaded: dense, punchy b-roll in the intro/hook, then sparse and precise through the body.
• But "skip" is the LAST resort, not the default. Before proposing skip for a beat, walk the full palette out loud — receipt? headline? face? product UI? concept graphic? — and only skip when every lane genuinely fails. A rhetorical line with no proper noun is exactly when a sentiment receipt or a concept graphic shines.

Understand the TOPIC first, then source the MEANING — not the keywords

1. Read the whole transcript and understand the thesis BEFORE sourcing anything. Context decides what illustrates each line.
2. B-roll illustrates the POINT, not the words. The proper noun in a sentence is often NOT the referent:
   • "X from Company" → the person and their work, not the company logo.
   • "like Company did" → the thing Company did.
   • "what Person said" → the said-thing (their quote/post/essay), not their face.
3. Literal vs evocative: concrete nouns (a product, a named person, an event) → show the actual thing. Actions & abstractions → show something that conveys it; don't reenact literally.
4. Mandatory reference sweep — every beat: is there a REAL ARTIFACT behind this line? A quote, a stat, "people are saying", a named company event, "I saw/read" — almost always means a tweet, headline, review, or post exists. That artifact is a default candidate; sourcing it is the skill's job, not an extra the user must request.

Phrase-type → what to source (the judgment table)

Genre → coverage defaults (what type, how much)

Genre predicts b-roll TYPE and density better than topic does (style + cadence answers from intake override these):

• Competitor / drama → receipts dominant, heavy (~40–60% coverage)
• Opinion / explainer → text/concept cards + receipt bursts (~20–30%)
• Storytelling / listicle → people, archival, products (~40–60%)
• Podcast / webinar / interview → light punctuation (~5–10%); b-roll marks references & claims, the talking head carries the rest

Routing — three+ kinds of b-roll go to three+ sources

Classify EVERY moment before searching:

⛔ Cards never replace real footage of a literal thing. If the beat names a concrete entity (grape varieties, a product, a place) and real footage exists, a generated text card is a FAIL — even if the user's fingerprint shows they like cards. Cards are for ideas with NO literal footage. (2026-06-11: a "three grapes" beat got a navy text card while the official film had the actual clusters — wrong.) | Cultural / Meme | A creator clip or joke where taste decides | NEVER searched or fetched by the agent. Propose the MOMENT + register ("punchline at 2:31, deadpan") in the plan; the user supplies the meme from their library — or strikes the beat. Agent-found memes have failed every time they've been tried. |

Litmus (in order): Happening now? → Receipts. A person / product / event? → Entity (official source). An abstract idea? → Concept (motion-graphics). A reaction beat? → Meme (user's library).

YouTube's sweet spot is the Entity route (people, products, historical moments). Don't force it onto abstract ideas — those are Concept jobs.

Person clips — source the MOMENT, not the NAME

A clip merely containing the person is NOT relevant b-roll (the #1 person-clip failure):

1. Write the mention-context first: what is the line saying ABOUT the person — the trait, the action, the claim, the event?
2. Query = person + mention-context, never the bare name. "Steve Jobs iPhone keynote 2007", not "Steve Jobs". Bare-name searches return generic press-junket clips.
3. Verify before presenting: for each candidate, fill in "in this clip, X is <doing/saying what, where, when>" from the title/date/auto-subs. Can't fill it in → not a candidate.
4. No context match found → say so; offer the canonical clip explicitly flagged "generic", or switch palette to their work/quote/headline (often better anyway).
5. "The show/podcast" ≠ "this episode" — a reference to a show sources the show's persistent branding, not one episode's guest art.

The palette — MIX it, never default to website screenshots

• Faces (video) — for a named person, a live clip of them talking (never a frozen headshot). Partial-frame / split-screen subjects → blurred-fill, never hard cover-crop. For a podcast/panel edit, the guests are ON CAMERA in the source recording — crop their tile as live video instead of hunting externally. A headshot of someone the audience won't recognize is DEAD b-roll — for niche people, show their WORK (their post, product, talk) instead of their face; famous faces should appear in context/action, not as static portraits. ⛔ And NEVER cut to a speaker's own tile as b-roll inside the same video they're speaking in — the audience is already looking at them; it reads as a glitch. Tile-cropping is for using their face in OTHER videos.
• Product / UI — the actual app UI or a real screen-recording (prefer own-recording > official channel > nothing; reject random third-party tutorials). Demos must be the MOST RECENT available — product UIs change fast; check upload dates, present them next to candidates.
• Receipts — tweets, headlines, reviews, search results. For a named company, prefer a news headline about a real event (IPO, funding, milestone) over the homepage.
• Reference screenshots — the real post/essay/page cited (an authentic screenshot beats a synthetic quote-card). The subject's own website, captured full-page and cropped per viewport, is a goldmine — history pages, team photos, maps, product pages.
• Concept motion-graphics — for ideas, charts, stats. Build on-brand; never synthetic-looking stock.
• Real / evocative footage — stock that conveys a story/action/mood. Eyeball every frame for watermarks, burned-in captions, and AI-slop.
• Memes / reactions — from the user's curated library only; the agent proposes the moment, never the meme. If the profile or the user says no memes: the category does not exist.

If a plan is >60% website screenshots, it's wrong.