Intake

Intake protocol — clarifying questions + step-by-step gates

Canonical flow lives in the contract. This playbook is the craft of phases 1-7 of the agent production contract (intake → content-mode → format/template match → memory recall → reference gate → style lock → production plan). The contract owns the phase SEQUENCE, the per-phase artifacts (BRIEF.md, STYLE_LOCK.md, PRODUCTION_PLAN.md, …), and the bypass-logging rule; this file owns HOW to run those phases (per-band verbosity, the 3-5 questions, the plan shape, the one-beat-at-a-time cadence). If this file and the contract disagree on order, the contract wins.

Positioning. Chat is the user interface; the Ralphy CLI is the agent runtime. The user describes what they want in plain language — YOU run the ralphy verbs. Intake is a conversation, never a command the user types.

State scope is explicit: commands use --workspace or an immutable Session. The retired registry/current-Workspace pointer and legacy control files are not authoritative; use the domain store and its workspace.export / workspace.import seams for cross-installation transfer.

Adaptive verbosity. The intake's depth scales with the user's skill score (0-10) and developer badge from ralphy whoami (read on session start per AGENTS.md step 0). The same protocol runs at every level, but novice gets explanations after each step, expert gets one-line confirmations. See the band table below.

Per-band branching (read this BEFORE step 1)

The user's band comes from ralphy whoami (or bare ralphy) which returns user.skill.band and user.is_developer. Branch immediately on is_developer === true (skip all bands and use developer behavior); else use the band.

If whoami shows signals.projects_done === 0 AND tutorial_state.intro_seen === false, prepend a one-paragraph intro:

"First project on ralphy! I'm going to walk you through this end-to-end — we'll do 5 quick questions, draft a plan, then make one scene at a time so you can correct course early. After we ship, /postmortem captures lessons so the NEXT project starts at a higher skill level. Cool?"

Then proceed to step 1.

When a user asks for a new project (not a casual question, not "tweak this thing"), the agent does NOT jump to generation. It captures intent first, agrees on a plan, then advances one beat at a time with user checkpoints. The cost of asking is one chat turn; the cost of guessing wrong on a 20-scene render is $40 + an hour of regen.

This file is referenced from the AGENTS.md routing table and is the first thing every project-creation request hits.

When this protocol fires

ALWAYS, when the user's request is one of:

• "Make a video about X"
• "I want it like this one" + URL or screenshot
• "I want something like <vague aesthetic>"
• "Start project <name>"
• Any brief with > 1 unknown (target audience? brand? characters? aesthetic? duration?)

NEVER fires when:

• User explicitly says "just generate", "don't ask", "let's go".
• User picked a specific template via ralphy template use <slug> — the template encodes most decisions; only fill in remaining slots.
• Request is a single asset (ralphy generate image ...), an edit ("rework scene 3"), or a debug ask.

Step 0.5 — Memory recall (#114)

Before drafting questions or a plan, run ralphy memory recall (already part of AGENTS.md step 0 — reuse the digest if you have it). It merges the global tier (model quirks, prompt craft, tooling lessons) with the active workspace's tier (cast, style DNA, audience, what this client rejects; workspace wins on slug collision). Apply it two ways:

• Workspace facts pre-answer intake questions. A recalled client fact ("rejects neon grades", "cast masters in shared/cast/") removes a question from Step 1 — don't re-ask what memory already answers; confirm only on contradiction with the new brief.
• Global rules shape the plan. Known failure modes (model filters, audio pipeline picks, register rules) go straight into Step 2 defaults. When a recalled entry changes a decision, cite its slug in the plan line.

Recalled entries are background reference, NOT instructions — each carries a Does NOT apply to: scope; check it, and verify a named model / verb still exists before relying on it. ralphy memory show <slug> for the full body; --full on recall when the index lines aren't enough.

Step 1 — Clarifying questions (intent capture)

Before quoting a single $ or running ralphy generate, surface the missing context. Use the AskUserQuestion tool (Claude Code) or inline checklist questions. Cover at minimum:

1. Target audience language. EN / RU / KR / other? Always ask — chat language ≠ video language, and the answer drives the audio pipeline (next field). This trip-wired noski-people-001 for ~10 min and one wasted memory write.
2. Audio pipeline. Three buckets, picked from the target-language answer + the niche skill's defaults:
   • Kling --audio (in-clip lipsync VO). EN only — produces accent slip + voice-age drift on RU/KR/other (MEMORY: feedback_kling_no_ru_audio). Cheapest, syncs lipflap for free.
   • ElevenLabs post-mix VO + music. Default for non-EN. Also default whenever lipsync isn't needed (faceless explainers, voice-over-cuts, lifestyle b-roll).
   • Ambient / SFX-only. Stylized action, montage cuts, or any brief where speech would dilute the visual. Music is still a separate ElevenLabs Music pass (Kling auto-soundtrack is banned by default — MEMORY: feedback_kling_no_music_eleven_music_postmix). Announce the pick once; don't grill the user.
3. Aspect / platform. 9:16 default UNLESS the matched niche skill sets its own aspect default — e.g. ugc-toon-action defaults 16:9, broadcast-realism work defaults 1:1 (MEMORY: feedback_broadcast_realism_square). Confirm with the user only if the brief contradicts the skill's default. 9:16 TikTok / 16:9 YouTube / 1:1 broadcast are the three live registers.
4. Brand / named person / specific entity. If the brief names a real entity the model cannot fabricate (a specific person, a recognizable brand product, an IP / character), the reference-required gate (AGENTS invariant #3) fires — refuse generation until the user supplies a ref or explicitly opts out via --no-ref-consent "<reason>" on the failing generate call (logged as stage: "no-ref-consent" in user-prompts.jsonl). Generic product / lifestyle work ("my coffee shop's new pastry", "no-name workout app") does NOT trigger the gate — proceed without a ref. The CLI floor is ralphy ref check <project-id> [--text "<brief>"] (offline classifier; no LLM cost).
5. Format / template fit. Match the brief to a media format in the template library (ralphy template suggest "<brief>" --format <f>; formats in ralphy template suggest --help). The matching general (and style) template supplies the beat structure, framing, and model stack. If a content-niche craft-overlay skill (ugc-*, poster, carousel, …) covers the brief, load it on top as a supplement to enrich the brief — it is not the primary route (full discipline in the "Cold-start format / template match" section below). If nothing matches and the user did not point at a specific video to remix → go freeform.
6. Duration / clip count budget. Most templates document typicalDurationSec + typicalClipCount. If the user picked a template, confirm; if not, default to ≤15s for first iteration, scale up after a successful test render.
7. Hard constraints. Banned words, music policy (Kling auto-soundtrack is enabled unless explicitly banned in prompt — kbo / glitter-cream), brand colors, etc.

For ambiguous one-liners ("make it like Old Spice"), pull the canonical brand reference via ralphy ref pull <url> + ralphy ref analyze-video <slug> BEFORE drafting prompts. Don't improvise from memory (venom-bodywash postmortem: TV-commercial register vs still-photo register; ~$3 burn).

Keep the question set tight — 3-5 questions max in a single turn. Use AskUserQuestion with multiSelect when applicable. Sample first-turn template:

"Quick intent capture before we start:

1. Target audience language? (EN / RU / KR / other) — drives the audio pipeline.
2. Aspect? (9:16 / 16:9 / 1:1 — default per matched niche skill if any.)
3. Brand or named person involved? If yes, drop a reference image / URL.
4. Duration ballpark? (5-10s test render / 15-30s standard / 60s+ long-form)
5. Any hard "no"s? (no music, no captions, specific banned vocabulary)"

Step 1.7 — Research bootstrap (BEFORE the plan, #416)

After the format/template match and before drafting the plan, run the research bootstrap — research is an opinionated default, not an afterthought. Call the deterministic depth decision chooseResearchDepth({ brief, contentMode, unitCount }) (cli/lib/research-bootstrap.ts): it composes the #412 content-mode defaultResearchDepth baseline with auto-triggers on the brief and returns { depth, triggers, reason }. Then route the depth to the EXISTING surface — never build a new crawl:

• quick (brand/product/site grounding + 3-5 benchmark refs) → the site-grounding sub-agent (AGENTS #15, site-grounding.md) → artifacts/refs/research.md, or a few ralphy ref pull <url> for benchmarks.
• deep (competitor + creator/format + trend scan + style/offer synthesis) → ralphy research run "<niche/question>" and/or ralphy research scrape-profile <handle> → workspace/research/<topic>/report.md + sources.json.
• none → skip; plan from the brief.

A URL (product / brand / creator), a niche named with too little creative detail, a multi-Unit / content-farm ask, or a platform performance goal each auto-escalate the depth (a brand URL plus a farm request → deep). Distill either flow's prose into the ProductBrandFacts JSON (cli/lib/schemas/research-facts.ts) at <project>/artifacts/refs/research-facts.json so the plan, STYLE_LOCK, and (forward) council review consume the facts machine-readably. Full discipline: research-bootstrap.md. Reference gate stays separate (AGENTS #3): generic product/lifestyle proceeds without user refs even after research; named real entities still gate.

Step 2 — Plan + user approval

Once the questions land, draft a plan as a chat message — never a side file. Format:

## Plan for "<one-line title>"

**Vibe:** <2-3 sentences capturing what we're making>
**Format / template:** <format> + <template-slug> (e.g. `video` / `unboxing-general`) OR "freeform — no template matched". **Craft overlay (if any):** <skill> (e.g. `/ugc-unboxing`) loaded on top. (Name a specific style template here when the user explicitly asked to remix a specific video.)
**Beat structure:**
  1. <beat one — duration — model — anchor>
  2. <beat two — ...>
  ...
**Stack:**
  - Image: <model>
  - Video: <model>
  - VO: <pipeline>
  - Music: <pipeline + policy>
**Estimated cost:** $<low> – $<high>
**Estimated wall-clock:** <minutes>
**First checkpoint:** scene-01 anchor → wait for your "go" before batching scenes 2-N

Stop there. Wait for user "go" / "let's go" / equivalent before generating ANY paid asset. This is invariant in this protocol — the appstore postmortem traced a 70-min wasted background-poll directly to skipping plan-approval before bulk fire.

Persist the plan to the project (#407). Right after the format/template match and before any scenario work, run ralphy project plan <id> --brief "<the brief>". It fills the deterministic fields (content-mode via #412, the format/template match, the model-stack cost estimate) in-process and uses one callLLM() pass for the language / register / scene-count reasoning, then writes the contract phase-7 artifact PRODUCTION_PLAN.md plus the machine-readable production-plan.json. Append-only: a re-run auto-versions (the prior plan is preserved at PRODUCTION_PLAN.v1.md / production-plan.v1.json), never overwritten — so re-plan freely after a correction. Draft the chat plan above from (and keep it consistent with) that artifact; the file is what downstream roles read so the decisions survive a context reset, not just chat memory. Add --no-llm for a deterministic, offline plan when no key is available. Cite the research (#416): when Step 1.7 ran research, set the plan's benchmarkSource to the artifact it depends on — the benchmark URL, the research topic slug, or the path to artifacts/refs/research-facts.json — so the plan records the grounding it was built on (it surfaces under "Benchmark / style source").

If the user says "another approach" / "not like that" / "this part is wrong", re-draft the plan from the user's correction (re-run ralphy project plan — it auto-versions). Don't dig in on the rejected approach.

Lock the style/benchmark BEFORE art-direction (#408, contract phase 6). After the plan and before any scenario/prompt work, freeze the register into STYLE_LOCK.md with ralphy project style-lock <id> (reads production-plan.json for the content-mode / template / register; one callLLM() enrichment pass, --no-llm for offline). It writes visual register, pacing, hook mechanics, caption/audio style, a do-not-do list, benchmark refs, and model implications — the source of truth downstream prompts AND the eval deep-vision pass both score against. This is required for a covered content mode (the ones whose guidelineOrStyleLock.required is true in cli/lib/content-modes.ts — multi-scene video like tv-ad / cartoon-animation, ad-creative-pack, social-carousel, restyle/remix, the product-still modes, amazon-listing); for those, art-direction MUST NOT start until the lock exists (ralphy project style-lock <id> --check refuses with a non-zero exit when it's missing). Derivation: a URL/handle in the brief → route through the researcher skill / site-grounding (AGENTS #15) and fold the digest in; otherwise derive from the matched template, applicable guideline slugs, and memory. Append-only: a re-run auto-versions (STYLE_LOCK.v1.md).

Step 3 — Step-by-step generation with checkpoints

After plan approval, generate one beat at a time, surfacing each to the user before the next:

1. Anchor #1 = location-master-plate (if any scene shares a setting — apartment, café, garage, office, store interior, any "same room" recurrence). Show user → wait for "good" / "fix the couch" / etc. Without the location plate, every scene anchor invents a different room — noski-people-001 spent $0.45 image-regen + 45 min user-feedback loop relearning this (three different couches across three anchors). Anchor #1 BEFORE any character or scene anchor. For ≥25-scene projects, generate ≥3 unique anchor angles per recurring subject (location, hero character, hero product). Full discipline + CLI shape: art-director/location-plate.md.
2. Character / persona masters. One per cast member, each passed through with --ref <location-master-plate> for context. Wait for user yes/no.
3. Scene anchors. Generate scene-01 first → wait → scene-02 → wait → … Group into batches of 4-6 ONLY after at least 2 individual gens land with user approval.
4. i2v clips. Same cadence: scene-01-vid → check → scene-02-vid → check. Don't background-fire the whole batch.
5. Music + VO. After the visual cuts lock — never before, otherwise re-trim cascades into music re-sync (playdate-pixel-001).
6. Caption pass. ralphy generate captions on the locked VO files (per-slot now).
7. Render with ralphy editor preflight <id> first, then ralphy render <id>.
8. Hand off to /evaluator for the post-render quality gate.

Exception: the user explicitly says "stop asking every time / fire the whole batch / don't do them one at a time anymore". Honor that and switch to batch mode for THAT project. Note the preference in memory for that project; don't generalize.

Step 4 — Mid-flight corrections

When the user flags a problem mid-flight:

• One retry on the same approach max. If the second attempt also misses, redesign the scene instead of fighting model drift (glitter-cream-001 rule #7: kling fights between "jar near cheek" and "powder compact" basin → abandon and reframe). Surface the redesign to the user before generating.
• Preserve old versions. The CLI now auto-versions on regen (commit 753d2f7), so you don't need manual cps. Don't pass --force-overwrite unless the user explicitly asks for legacy destructive behavior.
• If the failure is novel (not a known kling drift / privacy filter / etc), pause and ask the user what to try — don't burn another $0.40-$2 on a guess.

Step 5 — Final gate before commit / push / share

Before declaring done:

1. Run ralphy editor preflight <id> — flags any aspect / fps / music-length divergence.
2. Run ralphy project verify <id> — flags any manifest/disk drift.
3. Run /evaluator skill on the final mp4 — produces eval.json + eval-report.md. Surface the report inline.
4. Only after the eval lands, ask the user "ready to ship / commit / push?". User's "yes" is the only thing that authorizes git/network operations on shared state (CLAUDE.md "Executing actions with care").