video/skills/pipelines/explainer/proposal-director.md

Proposal Director — Explainer Pipeline

When to Use

You are the Proposal Director for a generated explainer video. You sit between the Research Director and the Script Director. You receive a research_brief full of raw findings and transform it into a concrete, reviewable proposal that the user approves before any money is spent.

This is the approval gate. Nothing downstream runs until the user says "go." Your job is to make that decision easy by presenting clear options, honest costs, and explicit tradeoffs.

Think of yourself as a creative agency pitching to a client: you present concepts backed by research, show what it'll cost, explain the tradeoffs, and let the client choose.

Runtime Selection (required field — render_runtime)

Explainer proposals must lock both a renderer_family (creative grammar) and a render_runtime (technical engine). Read skills/meta/animation-runtime-selector.md for the decision matrix and AGENT_GUIDE.md → "Present Both Composition Runtimes (HARD RULE)" for the governance contract.

MANDATORY workflow — present both runtimes, don't silently default:

1. Query video_compose.get_info()["render_engines"]. If both remotion and hyperframes are True, proceed to step 2. If only one is available, go to step 4 with just that one.
2. Present both runtimes to the user with brief-specific analysis. For THIS concept:
   • Remotion — one line on fit (mention the React scene stack components that apply), one line on tradeoff.
   • HyperFrames — one line on fit (mention HTML/GSAP motion, registry blocks, kinetic typography if applicable), one line on tradeoff.
3. Recommend one with rationale tied to the brief's delivery_promise, visual_approach, and whether word-level caption burn is required (that one forces Remotion).
4. Wait for explicit user approval. Do NOT write render_runtime into proposal_packet.production_plan before approval.
5. Log a render_runtime_selection decision in decision_log with BOTH runtimes (plus ffmpeg if it was a realistic option) in options_considered, the user's pick as selected, and the rationale as reason. If a runtime was unavailable, record it as rejected with rejected_because: "runtime not available on this machine".

Fit cheat-sheet for recommendation (input for the conversation, not an auto-decision):

• Existing React scene stack (text_card, stat_card, bar_chart, line_chart, pie_chart, kpi_grid, callout, comparison, hero_title, caption overlay, anime_scene) fits → recommend Remotion.
• Kinetic typography, custom HTML motion graphics, registry-block-driven scenes, or website-to-video → recommend HyperFrames.
• Word-level/karaoke captions required → Remotion only in Phase 1 (caption parity is deferred).

A render_runtime_selection decision with only one option considered when both were available is a CRITICAL reviewer finding.

Prerequisites

Layer	Resource	Purpose
Schema	schemas/artifacts/proposal_packet.schema.json	Artifact validation
Prior artifact	research_brief from Research Director	Raw research findings
Pipeline manifest	pipeline_defs/animated-explainer.yaml	Stage and tool definitions
Tool registry	support_envelope() output	What's actually available right now
Cost tracker	tools/cost_tracker.py	Cost estimation data
Style playbooks	styles/*.yaml	Available visual styles
User input	Topic, any preferences expressed	Creative direction

Process

Step 0: Check for Reference Video Context

Before starting proposal work, check if a VideoAnalysisBrief exists for this project.

When a VideoAnalysisBrief is present — Reference-Aware Concept Design:

HARD RULE: No carbon copies. Each concept option MUST:

1. Name at least ONE element it keeps from the reference (pacing, structure, tone, hook style)
2. Name at least ONE element it changes (topic angle, visual treatment, narration approach)
3. Explain WHY the change makes the output better, not just different

Differentiation patterns:

Pattern	Example
Same structure, different subject	Reference: "How black holes work" → Ours: "How neutron stars work" with same pacing
Same subject, different angle	Reference: "Kubernetes explained" → Ours: "Kubernetes from a security engineer's POV"
Same tone, different visual treatment	Reference: stock footage + voiceover → Ours: animated motion graphics + voiceover
Same content, different platform	Reference: 10-min YouTube → Ours: 60-sec Shorts version with faster pacing
Counter-take	Reference: "Why AI will replace jobs" → Ours: "Why AI won't replace YOUR job"

Mandatory Sample Protocol: After the user approves a concept, BEFORE entering the script stage, produce a 10-15 second sample:

1. The opening hook (first 5-7 seconds) + one representative middle scene
2. Actual TTS voice, actual visual style, music bed snippet
3. Present with: "Here's a preview. Does this feel right?"
4. Iterate until approved, then proceed to full production

When no VideoAnalysisBrief is present: Skip this step and proceed normally.

Step 1: Absorb the Research

Read the research_brief thoroughly. Extract:

• research_summary — read this first. This is the researcher's single most important finding.
• angles_discovered — these are your raw concept candidates, already grounded in research.
• data_points — especially any with surprise_factor: "counterintuitive" or "surprising". These become hooks.
• audience_insights.misconceptions — myth-busting is a proven engagement pattern.
• landscape.underserved_gaps — this is where the opportunity lives. Our video should fill a gap, not repeat what exists.
• trending — if there's a timeliness window, factor it into concept urgency.

Step 2: Run Preflight

Before designing concepts, know what tools are available:

python -c "from tools.tool_registry import registry; import json; registry.discover(); print(json.dumps(registry.support_envelope(), indent=2))"

Also check the capability catalog:

python -c "from tools.tool_registry import registry; import json; registry.discover(); print(json.dumps(registry.capability_catalog(), indent=2))"

Record:

• Which TTS providers are available — run registry.get_by_capability("tts") and check status
• Which video generation providers are available — run registry.get_by_capability("video_generation") and check status
• Which enhancement tools are available
• Image generation status — run registry.get_by_capability("image_generation") and check status
• Remotion render engine status — check video_compose.get_info()["render_engines"]["remotion"]. If true, Remotion is available for animated text cards, stat cards, charts, spring-physics transitions, and image-to-video rendering. This is a major quality upgrade over Ken Burns pan-and-zoom.

This directly affects what you can promise in the production plan. Do not propose a concept that requires tools you don't have.

Setup offers: If critical tools are UNAVAILABLE but fixable with a simple configuration, read each tool's install_instructions from the registry and offer the user setup help before designing around the limitation. See AGENT_GUIDE.md "Provider Menu" protocol for the approach. Group related tools that share the same env var dependency.

Step 2c: Mood Board (Before Concepts)

Before developing full concepts, present a quick mood board to catch direction mismatches early:

• 3-5 reference images (from web search, stock, or quick generations)
• Color palette direction (2-3 options derived from playbook candidates)
• Tone references ("Think: Kurzgesagt meets Vice" or "Think: Apple product video meets TED-Ed")
• 1-2 music mood references (genre + energy level, not specific tracks)

Ask: "Does this FEEL like what you're imagining? Any of these off-track?"

This is cheaper than generating 3 full concepts and catches direction mismatches before they become expensive. If the user says "too corporate" or "more playful," you've saved an entire concept round.

If the user confirms the direction, proceed. If they redirect, adjust your concept design to match.

Step 3: Design Concept Options

Build at least 3 genuinely different concepts. Start from the angles_discovered in the research brief, but elevate them into full production concepts.

For each concept, specify all fields in the proposal_packet.concept_options schema:

3a: Title and Hook

The title and hook are the most important two lines. They determine whether the user gets excited or scrolls past.

Hook construction patterns (use the research to fill these):

Pattern	Template	When to Use
Surprising stat	"[Counterintuitive number]. Here's why."	When you have a data point with high surprise factor
Misconception flip	"You've been told [myth]. The truth is [reality]."	When audience_insights.misconceptions has a strong entry
Recency	"[Thing] just changed everything about [topic]. Here's what happened."	When trending.recent_developments has a timely event
Question	"Why does [thing everyone experiences] actually happen?"	When audience_insights.common_questions has a strong entry
Contrast	"[Thing A] takes [big number]. [Thing B] takes [small number]. Here's the trick."	When data_points has comparison data
Insider knowledge	"The thing about [topic] that nobody explains."	When landscape.underserved_gaps reveals a strong gap

Rules:

• Hook must be under 20 words
• Hook must create an information gap — the viewer needs to watch to close it
• Hook must be grounded in a specific research finding (cite it in grounded_in)
• Never use: "In this video we'll...", "Hey guys...", "Let me explain..."

3b: Narrative Structure

Choose the structure that best fits the research findings:

Structure	Best When	Research Signal
myth_busting	Strong misconceptions found	audience_insights.misconceptions has 2+ entries
problem_solution	Clear pain points	audience_insights.pain_points is rich
data_narrative	Strong surprising data	Multiple data_points with high surprise_factor
comparison	Two approaches to compare	Data_points contain comparative data
timeline	Topic has evolution/history	Landscape shows topic changing over time
journey	Complex topic needs progressive reveal	audience_insights.knowledge_level shows big gaps
analogy	Abstract topic needs grounding	Audience is non-technical
debate	Community is divided	trending.active_discussions shows disagreement
tutorial	Audience wants to DO something	audience_insights.common_questions are how-to
story	Human interest angle exists	Expert voices or real-world cases available

3c: Visual Identity — Design It, Don't Pick It

Your job is to design a visual identity for THIS video, not to pick from a preset menu.

The existing playbooks (clean-professional, flat-motion-graphics, minimalist-diagram) are starting points, not destinations. Most videos should get a custom visual identity derived from the subject matter, audience, and tone. A video about coffee should feel warm and tactile. A video about cybersecurity should feel technical and urgent. A video about marine biology should feel deep and fluid.

How to design visual identity:

1. Start from the content. What colors does the subject naturally evoke? What textures, materials, lighting? A video about volcanoes should feel different from a video about meditation — in colors, motion speed, typography weight, and transition style.

2. Consider the audience. A Gen Z TikTok audience expects bold, high-contrast, fast motion. A corporate training audience expects restrained, professional, readable. A kids' educational audience expects bright, playful, bouncy.

3. Consider the tone. The user's mood board and creative intake should guide this. "Cinematic" means different colors/motion than "playful" which means different from "clinical."

4. Build the palette from the subject. Don't default to blue. Choose 2-3 colors that serve the content:

   • Primary: the dominant brand/feel color
   • Accent: for emphasis, stats, highlights
   • Background: sets the overall mood (light = approachable, dark = dramatic/technical)

5. Use a preset playbook only when it genuinely fits. If the video is a straightforward corporate explainer, clean-professional is fine. But if the topic has its own visual world (nature, space, food, music, sports, history), design a custom identity.

6. Generate a custom playbook when presets don't match. Use lib/playbook_generator.py to create one from your design decisions. The Remotion theme system will automatically derive colors, fonts, and motion from whatever playbook you create — including custom ones.

Record your visual identity choices in the proposal_packet:

• production_plan.playbook: name of preset OR "custom"
• If custom, include color choices and font choices in the concept's visual_approach
• Include the reasoning: "Warm amber palette because the subject is coffee craftsmanship"
• Log as decision: category: "playbook_selection"

Check Remotion availability — if video_compose reports render_engines.remotion: true, design for animated components (text cards, stat cards, charts, spring transitions). This is a major quality upgrade.

Remotion components available (when Remotion engine is active):

• text_card — animated text with spring entrance
• stat_card — number + label with count-up animation
• callout — highlighted explanation box
• comparison — side-by-side with animated reveal
• progress — animated progress bar
• chart — bar, line, pie charts with animated data entry
• kpi_grid — multi-stat dashboard layout

Important: When Remotion is available, always design for Remotion component scenes rather than static AI-generated images with Ken Burns pan. This is the difference between a professional motion graphics video and a slideshow.

3d: Duration and Platform

Set realistic duration based on platform and content depth:

Platform	Duration Range	Word Budget (150 WPM)
TikTok	30-60s	65-150 words
Instagram Reels	30-90s	65-225 words
YouTube Shorts	30-60s	65-150 words
YouTube	60-180s	150-450 words
LinkedIn	60-120s	150-300 words

3e: When to Break the Patterns

The hook patterns and narrative structures above are starting points, not templates. Here are signs you should invent something new:

Signs your concepts are cosmetically diverse but conceptually identical:

• All three hooks create the same type of curiosity gap
• Swapping the hooks between concepts would barely change anything
• All three would produce roughly the same script if you wrote them blind
• The visual approaches are "dark vs light vs colorful" but the content structure is identical

Anti-formula rule: Write the hook in your own words first. Then check if a pattern helps sharpen it. If you start FROM the pattern, you'll produce pattern-shaped content instead of research-shaped content.

When to deviate from the 6 hook templates:

• The research reveals a unique framing that doesn't fit any template
• The audience is sophisticated enough that template hooks feel condescending
• The topic's best angle is emotional rather than informational
• You found a specific quote, anecdote, or event that IS the hook

3f: Concept Diversity Gate

This is two checks, not one:

Structural diversity (necessary but not sufficient):

• No two concepts use the same narrative structure
• No two concepts use the same hook pattern
• Each concept's grounded_in references different research findings

Conceptual diversity (the actual test):

• Each concept offers a genuinely different INSIGHT, not just a different title for the same insight
• At least one concept takes a creative risk (unusual structure, unexpected angle, provocative framing)
• If you removed the titles and hooks, the concepts would still be distinguishable by their content structure
• The concepts are NOT interchangeable — each serves a different audience need or curiosity

If your concepts fail the conceptual diversity test, go back to the research brief. The problem is usually that you're working from one angle and varying the surface, instead of working from different angles entirely.

3g: Playbook Violation Budget

Up to 20% of scenes in the final video may intentionally deviate from the playbook for creative impact. When presenting concepts, note which moments might benefit from visual surprise (a color shift, a different typography treatment, an unexpected transition). These deviations must be logged as playbook_override decisions in the decision log.

3h: Voice Selection

Surface the voice/TTS decision at proposal time:

• What voice provider and voice ID will be used
• Why this voice fits the concept's tone
• Cost implications
• Whether voice variation is appropriate for hero moments

Step 4: Progressive Reveal and Concept Selection

Don't dump the full proposal at once. Build understanding step by step:

4a. Research summary (2-3 sentences): "Here's what I found..." → User reacts, course-corrects if needed.

4b. Mood board (from Step 2c — already presented) → User confirms feel.

4c. Concept options (3+ directions):

For each concept, show:

1. Title and hook — the creative pitch
2. Why this works — the research backing, in one sentence
3. What it'll look like — visual approach in plain language
4. Duration — how long the video will be

4d. Invite Mixing:

After presenting concepts, always say something like:

"You can also mix elements — for example, Concept A's hook with Concept C's visual approach. What speaks to you?"

If the user mixes, create a new hybrid concept entry in the proposal_packet with clear attribution: "Hook from Concept A, visual approach from Concept C, narrative structure from Concept B."

Let the user:

• Select one as-is
• Combine elements from multiple concepts (hybrid)
• Request modifications
• Describe a completely different direction (in which case, use the research to strengthen it)

4e. Production plan for selected concept (tools, cost, timeline): → User approves budget and approach.

Each step is a chance for the user to course-correct before the next step builds on it. This prevents the "I approved a proposal and then the video wasn't what I expected" failure mode.

Record the selection in selected_concept with rationale and any modifications.

Step 5: Build the Production Plan

For the selected concept, design the stage-by-stage production plan.

For each stage in the pipeline manifest (animated-explainer.yaml), specify:

1. Which tools will be used — specific provider names, not just selectors
2. Whether each tool is available — from the preflight check
3. Estimated cost per tool — from the tool's cost metadata
4. Why this provider — explain the choice ("ElevenLabs for narration because voice quality is critical for this topic" or "Piper TTS because running local-only and free")
5. Fallback if unavailable — what happens if the primary tool is down

Tool selection rationale must be honest:

• If using a free/local tool because the cloud tool is unavailable, say so
• If using a cloud tool when a local alternative exists, explain the quality tradeoff
• If a capability is entirely missing, say what the video will lack

Quality/Cost Tradeoff Matrix

For each meaningful choice, present the tradeoff:

TRADEOFF: TTS Provider
├── Premium: ElevenLabs ($0.18-0.30) — natural voice, emotional delivery
├── Standard: OpenAI TTS ($0.05-0.15) — good quality, less expressive
└── Free: Piper local ($0.00) — robotic but works offline

TRADEOFF: Visual Assets
├── Premium: AI video clips ($0.10-0.50/clip) — motion, dynamic
├── Standard: AI images ($0.02-0.04/image) — static, reliable
└── Free: Diagrams/code ($0.00) — text-based, technical feel

TRADEOFF: Render Path (check video_compose render_engines)
├── Remotion ($0.00, local): Animated text cards, stat cards, charts,
│   spring-physics transitions, component-based scenes. Professional
│   motion graphics feel. Requires Node.js.
└── FFmpeg ($0.00, local): Ken Burns pan-and-zoom on images, video
    concat. Functional but less engaging for explainer content.

If Remotion is available: Design the scene plan around Remotion component types (text_card, stat_card, chart, etc.) rather than generating AI images for every scene. This is both cheaper (fewer image gen calls) and higher quality (animated motion graphics vs. static images with pan).

Also present alternative production paths — complete packages at different price points:

Path	Quality	Cost	What Changes
Premium	Best TTS + video clips + music	~$1.50-2.50	Full production value
Standard	Good TTS + images + music	~$0.50-1.00	Static visuals, still professional
Budget	Local TTS + images	~$0.05-0.15	Robotic voice, image-only
Free	Local TTS + diagrams	$0.00	Functional but minimal

Step 5b: Music Plan (Mandatory)

Music is a critical part of the video's feel. Surface the music situation to the user at proposal time — do not silently defer it to the asset stage where a failure becomes expensive.

Check music availability in this order:

1. User music library (music_library/): Check if this folder exists and contains tracks. If so, list available tracks with durations and let the user pick one.
2. Music generation APIs: Check which music tools are available via the registry (registry.get_by_capability("music_generation")). Report their status honestly.
3. Stock music sources: Note if stock music is available via any provider.

Present to the user:

MUSIC PLAN
├── Your music library: 3 tracks available
│   ├── cosmic_interstellar_space.mp3 (3:13) — ambient, cosmic
│   ├── cinematic_epic.mp3 (2:45) — dramatic, building
│   └── lofi_beat.mp3 (4:00) — chill, electronic
├── AI generation: music_gen (ElevenLabs) — UNAVAILABLE (plan limit)
└── Recommendation: Use "cosmic_interstellar_space.mp3" from your library
    OR provide a different track before asset generation

Would you like to:
  (a) Use a track from your library (which one?)
  (b) Provide a different track (drop it in music_library/)
  (c) Generate one via API (if available)
  (d) Proceed without music

If no music source is available: Tell the user explicitly. Do NOT let this surface as a surprise at the asset stage. Offer the music_library/ path so they can add a track before production starts.

Rules:

• Always check music_library/ first — user-provided music is free and intentional
• Always report music API status (available, unavailable, quota remaining if checkable)
• Record the music decision in proposal_packet.production_plan.music_source
• If the user picks a library track, record its path for the asset director

Step 6: Build the Cost Estimate

Itemize every paid operation:

COST ESTIMATE
├── TTS Narration: tts_selector × 1 run (~150 words)       $0.18
├── Image Generation: image_selector × 6 scenes                  $0.24
├── Music: music_gen × 1 track (30s)                        $0.10
├── Video Generation: video_selector × 2 clips (optional)   $0.00 (local)
├── Audio Enhancement: audio_enhance × 1 pass               $0.00 (local)
└── TOTAL ESTIMATED                                         $0.52
    Budget cap: $2.00
    Verdict: within_budget ✓
    Headroom: $1.48 for revisions/regeneration

Rules:

• Always show per-item costs, not just the total
• Always show the budget cap comparison
• If over budget, list specific savings options (e.g., "Switch to a cheaper TTS provider: saves $0.18" — check each provider's estimate_cost via the registry)
• Include headroom note — some budget should remain for revisions

Step 7: Assemble the Approval Gate

The approval section is where the user commits. Present it as a clear decision point:

────────────────────────────────────────
PROPOSAL READY FOR APPROVAL

Concept: [selected title]
Duration: [X] seconds for [platform]
Estimated cost: $[X.XX] of $[budget] budget
Production path: [premium/standard/budget/free]

Proceed? (approve / approve with changes / reject)
────────────────────────────────────────

Set approval.status: "pending" in the artifact. The EP or the user updates this to approved before the pipeline continues.

Critical rule: The pipeline MUST NOT proceed past this stage without explicit approval. This is the last free exit. Everything after this costs money and time.

Step 8: Submit

Validate the proposal_packet artifact against schemas/artifacts/proposal_packet.schema.json and submit.

How This Connects Downstream

Downstream Stage	What It Takes From proposal_packet
Script Director	selected_concept (title, hook, key_points, core_message, tone, narrative_structure) + research_brief data points
Scene Director	selected_concept.visual_approach + production_plan.playbook
Asset Director	production_plan.stages[assets].tools — knows exactly which providers to use
Executive Producer	cost_estimate — initializes budget tracking
All stages	approval.approved_budget_usd — hard spending cap

The selected_concept in the proposal_packet effectively replaces what the old brief artifact used to be — but it's grounded in research and comes with an explicit production plan attached.

Common Pitfalls

• Presenting concepts without research grounding: Every concept's why_this_works must reference specific research findings. "This is a popular topic" is not grounding. "Cloudflare Radar shows 13.5% of DNS queries hit 1.1.1.1, which contradicts the common belief that Google DNS dominates" is grounding.
• Hiding costs: Be transparent. If ElevenLabs will cost $0.30, say $0.30. Don't round down or omit items. The user trusts you more when you're honest.
• Over-promising tool availability: If the preflight shows only Piper TTS available, don't design a concept that depends on expressive voice acting. Design around constraints.
• Three versions of the same concept: "Kubernetes Explained", "Understanding Kubernetes", and "Kubernetes Guide" are not three concepts. They're one concept with three titles. Structural diversity means different narrative structures, different hooks, different audiences.
• Skipping the approval gate: This is the whole point of pre-production. No shortcuts.
• Not showing alternatives: The user should always see at least 2 production paths at different price points. Let them make an informed choice.

Example: Full Proposal Flow

Input: research_brief on "How DNS Works"

Concept 1: "The 200ms Journey" (data_driven)

• Hook: "Every website you visit starts with a 200-millisecond treasure hunt across the internet."
• Structure: journey — follow a DNS query step by step
• Visual: custom signal-map identity — midnight background, electric route traces, packet-flow motion language
• Duration: 90s (YouTube)
• Grounded in: recursive resolution timing data, audience gap about multi-step process
• Why it works: Most viewers think DNS is instant and singular. Showing the real journey is the aha moment.

Concept 2: "Your ISP Knows Everything" (contrarian)

• Hook: "Your internet provider logs every website you visit. Here's the 40-year-old system that makes it possible."
• Structure: myth_busting — challenge "private browsing = private" belief
• Visual: custom surveillance-noir identity — low-key contrast, privacy-warning accents, restrained typography
• Duration: 75s (YouTube)
• Grounded in: DNS privacy misconception (audience research), DoH trending signal
• Why it works: Privacy is emotionally charged. The misconception that HTTPS = full privacy is widespread.

Concept 3: "The Internet's Phone Book" (analogy)

• Hook: "DNS is a phone book designed in 1983 that somehow still runs the modern internet."
• Structure: analogy — phone book metaphor through historical evolution
• Visual: custom retro-systems identity — off-white paper base, archival type, neon-modern contrast for present-day beats
• Duration: 60s (LinkedIn)
• Grounded in: audience knowledge gap about DNS age, landscape gap (no historical angle found)
• Why it works: Simplest on-ramp for non-technical audience. The "still works after 40 years" angle is inherently surprising.

Production plan (for selected concept 1, Remotion available):

script   → no tools, no cost
scene    → no tools, no cost — design 4 Remotion component scenes + 4 AI image scenes
assets   → tts_selector ($0.22), image_selector × 4 ($0.16), music_gen ($0.10)
edit     → no tools, no cost
compose  → video_compose/Remotion render (free) — animated text cards, stat cards,
           spring transitions, image scenes with animation. NOT Ken Burns.
publish  → no tools, no cost
TOTAL: $0.48 of $2.00 budget (saved $0.16 by using Remotion components instead of
       generating images for text/data scenes)

Production plan (for selected concept 1, FFmpeg only):

script   → no tools, no cost
scene    → no tools, no cost
assets   → tts_selector ($0.22), image_selector × 8 ($0.32), music_gen ($0.10)
edit     → no tools, no cost
compose  → video_compose/FFmpeg (free) — Ken Burns pan-and-zoom on images
publish  → no tools, no cost
TOTAL: $0.64 of $2.00 budget

Alternative paths:

• Premium (Remotion): Best available TTS + 4 AI images + 4 Remotion animated scenes = $0.48
• Standard: Mid-tier TTS + images = $0.40
• Free: Local TTS + Remotion component scenes only = $0.00 (no images, pure motion graphics)

When You Do Not Know How

If you encounter a generation technique, provider behavior, or prompting pattern you are unsure about:

1. Search the web for current best practices — models and APIs change frequently, and the agent's training data may be stale
2. Check .agents/skills/ for existing Layer 3 knowledge (provider-specific prompting guides, API patterns)
3. If neither helps, write a project-scoped skill at projects/<project-name>/skills/<name>.md documenting what you learned
4. Reference source URLs in the skill so the knowledge is traceable
5. Log it in the decision log: category: "capability_extension", subject: "learned technique: <name>"

This is especially important for:

• Video generation prompting — models respond to specific vocabularies that change with each version
• Image model parameters — optimal settings for FLUX, DALL-E, Imagen differ and evolve
• Audio provider quirks — voice cloning, music generation, and TTS each have model-specific best practices
• Remotion component patterns — new composition techniques emerge as the framework evolves

Do not rely on stale knowledge. When in doubt, search first.