# Write the brief > Start a film with bin/vawe new. It asks for the missing details and writes films//brief.md. Canonical: https://vawe.dev/docs/brief At the end of this page you have `films//page.html` (a valid starter) and `films//brief.md`, the brief that every later stage reads. This is stage 1 of the loop. You need a vawe checkout and an ask in your own words, such as “a 5 s sting for a coffee brand”. ## Steps ### Print the open details ```bash bin/vawe new hello --request "a 5 s sting for a coffee brand" --questions-json ``` This writes nothing. It prints the details that the ask leaves open, as calls of at most 4 questions each, with the required details first. The list lives in `DETAILS` in `harness/lib/measured-brief.mjs`. Without `--questions-json`, the verb prints the same questions as text and stops. ### Answer them in a file Write one `key: value` line for each detail. The keys are `subject`, `message`, `show`, `format`, `assets` and `ending`. ```text subject: Hollow, a coffee roaster for people who work from home message: the first cup is the best part of the day show: a cup filling, and the word "Hollow" format: 6 s, 16:9 assets: invent everything ending: the Hollow wordmark ``` For one answer only, pass `--detail key=value` (repeat the flag for more). ### Write the brief ```bash bin/vawe new hello --request "a 5 s sting for a coffee brand" --answers answers.txt ``` The verb picks a template from your ask and writes the two files. ### Take the defaults when nobody can answer ```bash bin/vawe new hello --request "a 5 s sting for a coffee brand" --defaults ``` `--defaults` guesses every open detail and marks each guess `(guess: change me)` in the brief. Use it when no person is there to answer, such as in CI. ## Choose a template Add `--from` to pick the template yourself. The default is the row of `guides/ROUTING.md` that your ask, the name and `--length` point at. ```bash bin/vawe new hello --from prompts/story-explainer.md --answers answers.txt ``` The `prompts/` folder holds 11 templates: | Template | Use when | | ----------------------------- | ------------------------------------------------------------- | | `showreel-one-liner` | no brief, a taste probe | | `brand-launch-from-url` | a real product from a URL, with its own kit and real captures | | `ui-morph-loop` | one element becomes 8 to 12 UI states and loops | | `reference-rebuild` | a reference mp4 must be matched | | `directors-brief-long-form` | over 60 s, or more than one session or agent | | `story-explainer` | explain a topic with invented visuals | | `music-video-beat-synced` | a song exists, and every cut lands on its beat | | `beat-sheet` | any film over one beat: the shot table before code | | `interactive-lab-capture` | a mechanism as a working model, then a scripted tour of it | | `production-brief-acceptance` | a claim that someone other than the author must sign off | | `pixel-art-sprite` | a 16-bit sprite loop on a logical canvas | `guides/ROUTING.md` maps a request to nine film types, and a type to one of the first nine templates (a sting takes `beat-sheet`). Two rules decide most cases: * A real product from a URL is a brand launch (`prompts/brand-launch-from-url.md`). * A reference mp4 that you must match is a reference rebuild. Use `--ref` and read [Match a reference film](https://vawe.dev/docs/match-a-reference). If two types fit, the shorter film wins. `--length`, `--aspect` and `--title` write their values into the brief and the page. `--aspect` takes any whole ratio, such as `16:9` or `9:16`. ## What you see The verb prints the question bank of the template with a default for each question. It writes `films/hello/brief.md` with each default filled in and marked `[unanswered: default taken]`. A field that the ask did not answer holds a guess marked `(guess: change me)`. The brief also has an “Ideas” section for the later stages. The verb ends with a `next:` line that names the next stage. ## The sections of the brief The brief is measured. A number that a program can measure is a number. A value that it cannot measure yet is a guess, marked `(guess: change me)`. The agent replaces each guess with a measured value or its own choice. The sections come in this order (`SKELETON` in `harness/cli/new.mjs`): 1. **Inputs.** The questions of the template, each with its default marked `[unanswered: default taken]`. 2. **Task.** What the film is, who sees it, the message and the spectacle second. 3. **Taken from.** Four to six reference frames, with what each one gives. 4. **Directions.** Three directions from three families (type, object, graphic). The agent picks one and says why. 5. **Signature.** Six dials: band, ease, stagger, seam, palette and thread. The page repeats them in ``. 6. **Look.** Numbers, not adjectives: colours, the typeface, type as a fraction of frame height. 7. **Design system and kit.** Palette roles, type, and the ground layers. 8. **States.** One static key frame per world, built from the kit before any motion. 9. **Ideas.** A table with four ideas for each beat and cut, and the pick with its reason. 10. **Board.** A plan for time: rhythm, a named move per cut, and the sound. 11. **Motion pass.** One row per cut, after the draft. 12. **Keep and swap.** For a reference film only: KEEP or SWAP for each line of its `SPEC.md`. 13. **Spec.** Three tables, in seconds and percent of frame: shots, words and objects. 14. **Acceptance.** Targets for the checks, with the measured value next to each one. 15. **Gates, Pitfalls and Deliver.** The order of the stills, the draft loop and the final, the pitfalls, and the files to hand over. 16. **First draft.** The taste list to read and the `bin/vawe dev` command. The slowest move runs at least 3 times the fastest (`taste/rules/speed-bands.md`). For the page contract, see [The page](https://vawe.dev/docs/the-page). ## What good looks like * Every `(guess: change me)` is a number or a name, not a hope. A value that you keep on purpose loses its marker. * The brief names a genre or a reference. A brief with no anchor reads like a template. * Facts only. The brief holds no plan for time yet: the board comes later. > The questions come once. Do not ask a second round. A wrong default is fixed at the critique. ## Common mistakes | What you see | Why | What to do | | -------------------------------------------- | --------------------------------------------------- | -------------------------------------------------------------------------- | | The brief is full of `(guess: change me)` | You used `--defaults` | Replace each guess with a measured value, or keep it and delete the marker | | The film type is wrong | The ask matched another row of `guides/ROUTING.md` | Run the verb again with `--from prompts/