From 3e4e64b68bda08ab827350c8e9f604da1aae17f2 Mon Sep 17 00:00:00 2001 From: shinyobjectz Date: Mon, 9 Nov 2026 06:15:10 -0800 Subject: [PATCH] Modes and verbs, past a recipe: each mode's decisions and how it fails, each verb's Decide and When it goes wrong; skills at raea-skills c507860 The five modes each name the choices that make or break the piece, with the default that comes easily and why to question it, and a table of how it fails (what you see, why, what to change). The nineteen verbs each say what to decide before changing anything and what a wrong pass looks like. --- sdk/guides/craft/modes/explain.md | 22 ++++++++++++++++++++++ sdk/guides/craft/modes/pitch.md | 25 +++++++++++++++++++++++++ sdk/guides/craft/modes/play.md | 22 ++++++++++++++++++++++ sdk/guides/craft/modes/story.md | 23 +++++++++++++++++++++++ sdk/guides/craft/modes/tool.md | 26 ++++++++++++++++++++++++++ sdk/guides/craft/verbs/adapt.md | 13 +++++++++++++ sdk/guides/craft/verbs/animate.md | 14 ++++++++++++++ sdk/guides/craft/verbs/bolder.md | 10 ++++++++++ sdk/guides/craft/verbs/clarify.md | 11 +++++++++++ sdk/guides/craft/verbs/critique.md | 11 +++++++++++ sdk/guides/craft/verbs/delight.md | 10 ++++++++++ sdk/guides/craft/verbs/distill.md | 10 ++++++++++ sdk/guides/craft/verbs/extract.md | 9 +++++++++ sdk/guides/craft/verbs/generate.md | 12 ++++++++++++ sdk/guides/craft/verbs/harden.md | 10 ++++++++++ sdk/guides/craft/verbs/layout.md | 10 ++++++++++ sdk/guides/craft/verbs/optimize.md | 9 +++++++++ sdk/guides/craft/verbs/polish.md | 9 +++++++++ sdk/guides/craft/verbs/quieter.md | 9 +++++++++ sdk/guides/craft/verbs/recut.md | 10 ++++++++++ sdk/guides/craft/verbs/regrade.md | 9 +++++++++ sdk/guides/craft/verbs/remix.md | 10 ++++++++++ sdk/guides/craft/verbs/retime.md | 10 ++++++++++ sdk/guides/craft/verbs/typeset.md | 10 ++++++++++ skills | 2 +- 25 files changed, 315 insertions(+), 1 deletion(-) diff --git a/sdk/guides/craft/modes/explain.md b/sdk/guides/craft/modes/explain.md index 40e1b0ae..497f07f1 100644 --- a/sdk/guides/craft/modes/explain.md +++ b/sdk/guides/craft/modes/explain.md @@ -25,11 +25,33 @@ everything, just one loop, all the way through. - **Honest time.** Cut the waits and keep the result at real speed. Never show a speed the product doesn't have. - **The payoff.** The last scene shows the result of the loop, the thing the viewer now knows how to make. +## The decisions + +- **The loop.** Choose the task a newcomer does most often. The easy default is the most impressive feature, but + a viewer can't repeat an impressive feature on day one. +- **The project.** Use a real project with real names: the person's own, if they gave you one. The easy default is + an empty demo workspace, and its blank lists teach nothing. +- **How close the camera sits.** Get close enough that the words that matter can be read at the size the piece + ships. A full-screen recording almost never is that close. +- **Voice or words on screen.** Use a voice for a walkthrough people choose to watch. Burn in captions when it plays + muted in a feed. Many pieces need both. +- **What gets cut.** Cut the waits, the loading and any mistake fixed on camera. Show the result at real speed. + ## The rut Feature lists read aloud. A cursor wandering over a full-size recording. Device mock-ups floating on a gradient. Narration that describes what the viewer can already see instead of why it matters. +## How it fails + +| What you see | Why | What to change | +|---|---|---| +| viewers lose the thread halfway | a scene relies on a step that comes later, or one scene holds two steps | reorder the scenes, or split the scene in two (`recut`) | +| the voice names something nobody can find | the name isn't on screen when it's said, or it's too small to read | zoom to it as it's said, or change the line (`clarify`) | +| it plays like a feature tour | the scenes don't move one project forward | rebuild it around one loop and one project | +| the cursor gets there after the voice | the cues were timed by eye | time the camera and the cursor from the transcript | +| it ends on a logo | the payoff is missing | end on the finished thing the loop made | + ## Check - Pace: hold each step until its result has landed, then move on. A step that depends on a later one confuses diff --git a/sdk/guides/craft/modes/pitch.md b/sdk/guides/craft/modes/pitch.md index 46a15fff..e555c621 100644 --- a/sdk/guides/craft/modes/pitch.md +++ b/sdk/guides/craft/modes/pitch.md @@ -20,11 +20,36 @@ A viewer who had no plan to watch stops, believes the brief's `believe:` line, a the angle isn't specific enough yet. - **Plan it.** Hook · problem · proof · ask as a storyboard, approved before anything renders. +## The decisions + +Each one has a default that comes easily. Question it before you take it. + +- **The belief.** Write the `believe:` line the way a viewer would repeat it to a friend. The easy default is a + feature ("it has AI editing"). A belief is what changes for the viewer ("my edit ships the same day"). +- **What opens.** The easy default is problem first, then proof. When the proof is striking enough to stop someone + scrolling, open on the proof, and let the problem be the reason it matters. +- **What carries it with the sound off.** Feeds play muted. The picture and the burned-in words make the argument, + and the voice adds to it. A piece that only the voice explains fails the mute test. +- **The length.** Use the delivery's length. Each cutdown is its own edit with its own hook (`motion/delivery`). The + easy default is the long cut stopped early. +- **The ask.** Use the action the brief names: install, try, book. The easy default, "learn more", only makes sense + when the brief has no real action. + ## The rut The template ad: white captions with one yellow word, a zoom on every sentence, a whoosh on every entrance. A big number with nothing behind it. Glass cards floating over footage. +## How it fails + +| What you see | Why | What to change | +|---|---|---| +| people leave in the first seconds | the opening is a logo, a slow push or a setup line | open on the proof or the sharpest line | +| viewers remember the ad but not the product | the proof is generic: stock footage, a mood, a claim with nothing shown | show this product doing its thing, on screen, as the voice says it | +| it reads as a template ad | a zoom on every sentence and a whoosh on every entrance | keep motion and sound for the two or three moments that carry the argument (`quieter`) | +| the ask goes by unread | the end card is up for less than two seconds, or sits under a platform's buttons | hold it long enough to act on, inside the safe zones | +| a claim nobody can stand behind | a number, quote or result that isn't in the brief | remove it, or ask the person for the real one | + ## Check - Mute it: does the picture alone make the argument? diff --git a/sdk/guides/craft/modes/play.md b/sdk/guides/craft/modes/play.md index 090eebd7..5cdb6a21 100644 --- a/sdk/guides/craft/modes/play.md +++ b/sdk/guides/craft/modes/play.md @@ -20,11 +20,33 @@ and hear, and when it ends they press to play again. - **Clear failure, quick restart.** The player sees why they lost and is playing again in a moment. - **Deterministic.** State lives in `useGameState` with a pure step, so a logged play renders back to the same pixels. +## The decisions + +- **The core move and its numbers.** Set the speed, the acceleration, how long a jump hangs and the frame where it + lands. The easy default is whatever the physics gives you. Tune the numbers by hand while you play. +- **What the camera shows.** Show what the player needs to see coming. The easy default is a fixed camera centred + on the player, which hides the danger on a fast run toward the edge of the screen. +- **The first minute.** Let the first obstacle teach the move. The easy default is a line of instructions. +- **The run and the restart.** Decide how long a run lasts and how quickly the player is back in after losing. Both + should be short enough that one more go is easy to say yes to. +- **Sound.** Give every input and every outcome a sound (`games`). Silence after a jump reads as a missed jump. +- **What is random.** Seed it from the game's state, so a logged play renders back the same. + ## The rut A title screen before anything happens. Controls explained in text instead of taught by the first obstacle. A score that means nothing. +## How it fails + +| What you see | Why | What to change | +|---|---|---| +| new players stand still | the goal or the player doesn't stand out | separate them by shape and contrast first, then by colour | +| the controls feel floaty or stiff | the feel numbers were never tuned: slow acceleration, no landing frame | tune them live, one at a time | +| deaths feel unfair | the cause wasn't visible: a hitbox bigger than the sprite, danger off screen | make hitboxes match the drawing, and show danger before it arrives | +| a replay doesn't match the play | some state lives outside `useGameState`: `Math.random()`, the clock, a ref | move it into the step, seeded from state (`harden`) | +| it stutters live | the frame costs too much | reduce the cost (`optimize`). Never swap in a video | + ## Check - Playtest it live, with real input, not from a rendered video. diff --git a/sdk/guides/craft/modes/story.md b/sdk/guides/craft/modes/story.md index 006cea7d..1f4bb5ed 100644 --- a/sdk/guides/craft/modes/story.md +++ b/sdk/guides/craft/modes/story.md @@ -24,11 +24,34 @@ they want the whole film. only repeat. - **One image to remember.** Decide which frame is the poster and build toward it. +## The decisions + +- **The feeling.** Name it in a word or two before you plan a single shot: homesick, giddy, dread. "Epic" and + "beautiful" describe a look, not a feeling, and they lead to shots with no subject. +- **The world's rules.** Decide what the colours mean, where the light comes from, which lens, and how the camera + moves. The easy default is choosing a look shot by shot from references, and that ends up as several films. +- **Each shot's subject.** Choose the person, object or action each shot is about. The easy default is a wide + establishing shot, so question every one. +- **What the music does.** It either leads, and you cut to its map, or it sits under the picture as a score. The easy + default is a cut on every bar. +- **The poster frame.** Choose it before anything renders, and build the edit toward it. + ## The rut A montage of pretty shots with no subject. Slow pushes on empty rooms. Every cut on the bar line. Grain, bloom and lens flare doing the work the idea should do. +## How it fails + +| What you see | Why | What to change | +|---|---|---| +| a montage nobody remembers | the shots have no subject | put a person, an object or an action in every shot | +| it plays like a slideshow | each camera eases to a stop before the cut | start and end each shot while the camera is still moving (`recut`) | +| the cutting feels mechanical | every cut lands on the bar line | cut on the song's events: downbeats, builds, stops, the drop | +| shots look like they come from different films | the light, colour or lens drifts from the world | re-light or regrade to the world's rules (`regrade`) | +| the narration explains the picture | a line repeats what is already on screen | cut the line, or give it what the picture can't show | +| the ending fizzles | nothing was built toward | end on the poster frame or the line the piece was made for | + ## Check - The arc: does the energy build, breathe and land, or stay at one level? diff --git a/sdk/guides/craft/modes/tool.md b/sdk/guides/craft/modes/tool.md index 292ab0cb..2f0d5571 100644 --- a/sdk/guides/craft/modes/tool.md +++ b/sdk/guides/craft/modes/tool.md @@ -20,11 +20,37 @@ The person finishes what they came to do, knows what happened, and never wondere - **Real content.** Lay it out with real names, real lengths and real numbers, never placeholder text. - **Built for real.** A screen for a raea app is built in the app itself, never mocked up as a picture. +## The decisions + +- **The task.** Decide what the person came to do, and the two or three steps that do it. The first screen opens on + that task. The easy default is an overview dashboard, which makes everyone hunt for the task. +- **Density.** Design for the person who uses it most. Someone who uses it all day wants more on screen and keyboard + shortcuts. Someone who opens it once a month wants less, with labels. +- **Where things live.** Follow the platform's conventions for menus, settings, shortcuts and Undo. The easy default + is a custom layout, and it costs every user a moment of looking. +- **What's in view and what's a click away.** Keep the task's next step in view. Put settings and rarely used + actions behind a click. +- **How an action answers.** Every action shows that it happened, at the place where it happened. A toast in a far + corner is easy to miss. +- **The target.** Choose web or native for the app (`motion/interface`). + ## The rut Cards in cards. A dashboard of numbers nobody asked for. Icons with no labels. Every element given the same weight. +## How it fails + +| What you see | Why | What to change | +|---|---|---| +| people ask "where is…" | the action is buried in a menu, shown only as an icon, or out of view | put the task's next step in view, with words | +| people don't know whether it worked | the action gives no answer where it happened | show the change in place | +| an error leaves them stuck | it says what happened, but not what to do next | say what to do, and clear the error once they act | +| it breaks with real data | a long name overflows, an empty list is blank, 500 rows are slow | design every state with real content (`harden`) | +| it looks busy | everything has the same weight, with cards inside cards | one accent, one level of container, and the rest quieter (`quieter`, `layout`) | +| keyboard or screen reader can't use it | controls have no role or label in tree.json | real buttons with words in them, and `role` and `aria-label` where there's no button | + ## Check - Do the task yourself, start to finish, at the size it ships. - Find the state nobody designed. +- `raea app check APP --png out/` with steps that walk every state, read PNG by PNG (`motion/interface`). diff --git a/sdk/guides/craft/verbs/adapt.md b/sdk/guides/craft/verbs/adapt.md index 24106293..0b1664fe 100644 --- a/sdk/guides/craft/verbs/adapt.md +++ b/sdk/guides/craft/verbs/adapt.md @@ -8,6 +8,13 @@ YouTube". The same piece made right for another size, length or platform; never - For each size, find what no longer fits: type that wraps, a face cut off, a part in a platform's button zone, a hold that's too long for a shorter cut. +## Decide +- Which size leads. Lay out the size the brief favours first, and make the others from it. The easy default is + designing at 16:9 and adapting down. A vertical made that way is a crop, however it was built. +- What each size drops. A smaller or shorter version loses a whole element, such as a secondary line or a shot. + Shrinking everything is not the answer. +- Whether a cut needs its own hook. A 6 s cut is a different edit from a 30 s one, not the first 6 seconds of it. + ## Change - Register one `` per size in the same root, sharing the parts; each lays out for its own frame (`raea guide motion/compositions`). Never scale or crop one size into another. @@ -19,3 +26,9 @@ YouTube". The same piece made right for another size, length or platform; never ## Verify - `raea render --composition ID --at 0,45,89` stills for every size; `raea check` on each export. - Every size says the same thing; nothing is cut off or crowded in any of them. + +## When it goes wrong +- Type that's tiny in 9:16 was scaled from 16:9. Lay out each frame for its own shape. +- A face sits behind a platform's buttons: place it from the safe zones, not by eye. +- The short cut ends mid-sentence. Cut on words, and keep the ending. +- The sizes drift apart after a later note. Change the shared part, not one composition. diff --git a/sdk/guides/craft/verbs/animate.md b/sdk/guides/craft/verbs/animate.md index fffbc761..419f6612 100644 --- a/sdk/guides/craft/verbs/animate.md +++ b/sdk/guides/craft/verbs/animate.md @@ -8,6 +8,13 @@ something that holds still, so each move says something. with nothing to say stays still. - Find the beats it lands on: the voice's words, the music's hits (`raea song FILE --plot`), the cuts. +## Decide +- What moves first in each beat, and what stays still. The easy default, everything entering at once, means + nothing leads. +- One easing and one speed for the piece: snappy for a pitch, slower and heavier for a story. +- Whether motion is the answer. A frame that feels static may need a cut (`recut`) or a shorter hold (`retime`), not + movement. + ## Change - Animate entrances, the one emphasis per beat and exits; leave everything else still. - One easing family for the whole piece; springs for things with weight, short eases for type (`raea guide @@ -19,3 +26,10 @@ something that holds still, so each move says something. - Play it at full speed, then step the frames around each beat: each move starts on its cue and settles before the next. - Nothing moves without a reason you could say in a few words. + +## When it goes wrong +- Everything bobs or drifts all the time. Idle motion with nothing to say pulls the eye from what does. Hold it + still. +- Moves land between beats because they were timed by eye. Take the cues from the transcript and the song's map. +- Type overshoots and wobbles: a spring on text. Use a short ease. +- A part pops or jitters on one frame, from an unclamped `interpolate` or state kept outside the frame. diff --git a/sdk/guides/craft/verbs/bolder.md b/sdk/guides/craft/verbs/bolder.md index 8f0c0017..21f02e3d 100644 --- a/sdk/guides/craft/verbs/bolder.md +++ b/sdk/guides/craft/verbs/bolder.md @@ -8,6 +8,11 @@ exists. Almost always one beat, not the whole piece. - Is it weak because of what's on screen, or because of what's around it? A beat often feels flat because the moment before it is just as loud. +## Decide +- Which beat. When the note doesn't say, pick the hook and tell the person which one you took. +- Which lever: quiet before it, a closer frame, a harder cut, or one sound. Pick one, and the next only if one + isn't enough. + ## Change - Contrast first: make the moment before quieter or stiller, so the beat lands by difference. - Then the beat itself: a closer frame, a harder cut on the downbeat, a larger scale change, one strong sound under it. @@ -16,3 +21,8 @@ exists. Almost always one beat, not the whole piece. ## Verify - Watch the beat with the two seconds before it. It hits now, and nothing else got louder to compete. + +## When it goes wrong +- Everything got louder and the beat still doesn't stand out. Pull back what's around it. +- Effects pile up: a shake, a flash and a zoom at once. Keep one. +- The bold moment outshouts the message: the product or the ask is now the second-loudest thing on screen. diff --git a/sdk/guides/craft/verbs/clarify.md b/sdk/guides/craft/verbs/clarify.md index 51d4df20..150c2515 100644 --- a/sdk/guides/craft/verbs/clarify.md +++ b/sdk/guides/craft/verbs/clarify.md @@ -8,6 +8,11 @@ The words: narration, captions, titles and labels. hearing, and each name the voice says that isn't on screen when it's said. - Find jargon, abstractions and lines that describe what the picture already shows. +## Decide +- Whose words: the vocabulary of the audience in the brief, not the team's or the product's. +- What the picture carries and what the words carry. A line that repeats the picture goes. +- Cut or rewrite. Try cutting the line first. Rewrite it only if the piece needs what it says. + ## Change - Plain, specific words in the person's own vocabulary. One idea a line. - Narration says why it matters; the picture shows what it is. @@ -16,3 +21,9 @@ The words: narration, captions, titles and labels. ## Verify - Play it with sound only, then with picture only. Both make sense; together they don't repeat each other. + +## When it goes wrong +- The lines got longer while getting "clearer", and a scene now runs over its words. Split the scene or cut a line. +- Plain turned vague: "it's easy", "everything you need". Use specific nouns and verbs. +- Captions no longer match the voice. Remake them from the new transcript. +- Cues drift after a rewrite. Re-time them from the transcript. diff --git a/sdk/guides/craft/verbs/critique.md b/sdk/guides/craft/verbs/critique.md index 59c0a3f2..41c235ab 100644 --- a/sdk/guides/craft/verbs/critique.md +++ b/sdk/guides/craft/verbs/critique.md @@ -8,6 +8,11 @@ Judge the piece as it rendered, not as you meant it, before you call it done or - Judge it against the brief (`believe:`, `audience:`), the person's taste, the mode's guide and the floor. - Run `raea check` for what can be measured, and judge the rest by the rubric (`raea guide rubric`). +## Decide +- Judge against the brief and the mode first, and the person's taste second. Your own taste is the easy default. +- Judge severity: would the audience notice this? If not, it is P2 or below, however much it bothers you. +- Rank the few that matter most. Thirty equal notes give the next pass nothing to act on. + ## Write it down - Each issue: where (the part or the moment), what's wrong, and why it matters to the audience. - Rank each one: P0 breaks the piece (a floor defect, a wrong fact), P1 the audience would notice, P2 makes it better, @@ -17,3 +22,9 @@ Judge the piece as it rendered, not as you meant it, before you call it done or ## Then - Fix P0 and P1 before showing anyone. `polish` works through the rest. + +## When it goes wrong +- The critique was written from the code or the plan, not from the render. +- Every issue is P2, so nothing is fixed first. +- A fix sanded off the strongest moment, because nobody named it. +- A clean `raea check` was read as the piece being good. The check finds defects; it doesn't judge the work. diff --git a/sdk/guides/craft/verbs/delight.md b/sdk/guides/craft/verbs/delight.md index b1e7a3ef..bdd5367d 100644 --- a/sdk/guides/craft/verbs/delight.md +++ b/sdk/guides/craft/verbs/delight.md @@ -7,6 +7,11 @@ detail that rewards attention, in the piece's own voice. - Is the piece right first? Delight on a piece that doesn't land is noise: fix the note's real problem before this. - Find a moment with room: a hold, a transition, the end card, a game's idle or its win. +## Decide +- Where it goes: a moment that has room. The opening is the easy default, and it's where the piece most needs to + be about its point. +- Whose voice it's in: the brand's, or the subject's. Never a generic flourish. + ## Change - One detail, maybe two: a character's blink, a sound on a hit, the logo doing one thing it only does here, a line of copy that's a little warmer than it has to be. @@ -16,3 +21,8 @@ detail that rewards attention, in the piece's own voice. ## Verify - Watch it as someone seeing it for the first time: the detail is noticed second, not first. - Take it out and watch again: if nothing is lost, it wasn't worth keeping. + +## When it goes wrong +- It upstages the message: people remember the joke and not the product. +- It's generic: confetti, sparkles, a bounce any piece could have. +- It repeats. A touch used in every scene stops being a surprise by the second time. diff --git a/sdk/guides/craft/verbs/distill.md b/sdk/guides/craft/verbs/distill.md index bb374799..7c5c71f7 100644 --- a/sdk/guides/craft/verbs/distill.md +++ b/sdk/guides/craft/verbs/distill.md @@ -7,6 +7,11 @@ and parts, until what's left is the piece. - Write the brief's `believe:` line next to the piece. Mark every scene, line, layer and sound that doesn't serve it. - Find the repeats: two shots that say the same thing, two lines that make the same point, two sounds in one moment. +## Decide +- What the piece is for: the `believe:` line decides what stays. +- Which of two good things stays: the one that serves the belief better, even if the other is prettier. +- The target length: the brief's, or the delivery's. + ## Change - Cut whole things before trimming parts: a scene, a line, a layer. Expect to cut good things. - Merge what repeats into the stronger one. @@ -15,3 +20,8 @@ and parts, until what's left is the piece. ## Verify - Say the piece in one sentence after watching it. It matches `believe:`. - The length is within what was asked. + +## When it goes wrong +- It's now too thin, because the proof or the payoff went. Put it back and cut elsewhere. +- Every part got a little shorter and nothing was removed. It's the same clutter, faster. +- Cuts land mid-word, or the music jumps. Cut on words and on the song's map. diff --git a/sdk/guides/craft/verbs/extract.md b/sdk/guides/craft/verbs/extract.md index 94c893d9..f6aecc42 100644 --- a/sdk/guides/craft/verbs/extract.md +++ b/sdk/guides/craft/verbs/extract.md @@ -9,6 +9,10 @@ the video". A brand kit read from finished work rather than a website. - From stills across them, find what repeats: the two or three colours, the faces and weights of type, the logo and how it's shown, how things move and cut. +## Decide +- Which work counts as the brand. Use what the person approved recently, not everything they've made. +- Rule or accident. A colour or move that appears once is an accident. Only what repeats goes in the kit. + ## Change - With a site, start from `raea brand DOMAIN`, then add what the work shows that the site doesn't. - Write what you found into the kit: `brand/brand.css` (`--brand-*` colours and fonts), `brand/brand.json`, and @@ -18,3 +22,8 @@ the video". A brand kit read from finished work rather than a website. ## Verify - A test card in the new kit sits beside a still of the old work and reads as the same brand. + +## When it goes wrong +- Colours sampled from footage (skin tones, a lamp) end up as brand colours. +- The logo came from a frame grab, so it's soft and slightly the wrong colour. Ask for the file. +- Guesses were written as facts. Mark each one in BRAND.md until the person confirms it. diff --git a/sdk/guides/craft/verbs/generate.md b/sdk/guides/craft/verbs/generate.md index 156a7ae2..2caf3571 100644 --- a/sdk/guides/craft/verbs/generate.md +++ b/sdk/guides/craft/verbs/generate.md @@ -8,6 +8,12 @@ the end card". Variants of one element to pick from, not of the whole piece. in. Everything else stays the same. - Three to five variants; more is a choice nobody wants to make. +## Decide +- The axis the variants differ on. "Style" is too vague an axis. Name it: the colour, the first line, how the title + arrives. +- How far apart the variants are. Make them far enough apart that a person can choose in one look. +- What to show: stills for a look, short clips for motion or sound. + ## Change - Variants in code: one component with a prop for what changes, one `` per variant, rendered as stills or short clips side by side. @@ -18,3 +24,9 @@ the end card". Variants of one element to pick from, not of the whole piece. ## Verify - Show them together, labelled plainly (A, B, C), with one line each on what it does differently. The person picks; then remove the rest from the composition. + +## When it goes wrong +- The variants differ in more than one thing, so the person can't tell what they're choosing. +- Five near-identical variants make a choice nobody can make. +- The chosen variant can't be made again because its prompt or seed wasn't kept. +- The variants that weren't chosen stay in the composition. diff --git a/sdk/guides/craft/verbs/harden.md b/sdk/guides/craft/verbs/harden.md index a3c9600a..800da03e 100644 --- a/sdk/guides/craft/verbs/harden.md +++ b/sdk/guides/craft/verbs/harden.md @@ -8,6 +8,11 @@ edges. resizing, the very first frame and the last, a very long name, nothing at all. - Reproduce the note's case first, live, with real input. +## Decide +- Which edges matter here. For a game, that's input and timing. For a tool, that's data and its states. +- What each case should do: ignore the input, queue it, or refuse with words that say why. Decide it in the step, + once. + ## Change - Fix the cause in the pure step (`useGameState`), not a guard in the view. - Every state has a picture: empty, loading, error, won, lost. @@ -15,3 +20,8 @@ edges. ## Verify - Play the case again live, then the cases next to it. Run the replay check. + +## When it goes wrong +- A guard in the view hides the bug, and the replay no longer matches the play. +- The fix for the reported case breaks the case next to it. Play the neighbours too. +- An error state has no way out. diff --git a/sdk/guides/craft/verbs/layout.md b/sdk/guides/craft/verbs/layout.md index 23cab61c..d7fa4d95 100644 --- a/sdk/guides/craft/verbs/layout.md +++ b/sdk/guides/craft/verbs/layout.md @@ -9,6 +9,11 @@ space", "the logo's lost". Where things sit in the frame and how much room each `raea guide motion/placement`), edges that almost line up but don't. - Look at the frame at the size it ships (a phone for 9:16), not at full resolution. +## Decide +- The focal point of each moment, before you move anything. +- One grid and one margin for the whole piece, from the brand kit when it has them. +- The size you judge at: the size it ships, a phone for 9:16. + ## Change - One focal point per moment. Make it bigger or give it more room; make the rest smaller rather than moving it away. - Put parts on a grid: shared left edges, shared baselines, the same margin on every side (`raea guide motion/layout`). @@ -18,3 +23,8 @@ space", "the logo's lost". Where things sit in the frame and how much room each ## Verify - Stills at the same frames, before and after (`raea render --at`), at ship size. The eye goes to the right place first. - `raea check` reports no overlap or out-of-safe-zone parts. + +## When it goes wrong +- Everything is centred and the same size, so the eye has nowhere to go first. +- Space is spread evenly, so the frame looks empty rather than calm. +- A layout fixed for one size breaks in another. Check every composition. diff --git a/sdk/guides/craft/verbs/optimize.md b/sdk/guides/craft/verbs/optimize.md index 28b4d7c7..5b646cc6 100644 --- a/sdk/guides/craft/verbs/optimize.md +++ b/sdk/guides/craft/verbs/optimize.md @@ -8,6 +8,10 @@ The same piece, lighter: smaller files, faster renders, smooth play. - Find the cost: footage at a far higher resolution than the frame, 3D lights and shadows nobody sees, a model with more triangles than pixels, per-frame work that could be computed once. +## Decide +- Which cost the note means: the file's size, the render's time or the game's frame rate. Each has its own fix. +- What may change. The look stays the same unless the person agrees to a trade. + ## Change - Delivery: `--quality` per use (`raea guide rendering`); a share copy for sending (the skill's ffmpeg line). - Footage: `raea mezz` for long-GOP sources; trim to the parts used. @@ -17,3 +21,8 @@ The same piece, lighter: smaller files, faster renders, smooth play. ## Verify - The same measurements, before and after. The look is unchanged in stills at the same frames. + +## When it goes wrong +- The look changed: banding in gradients, blotching in dark frames, soft detail from a bitrate set too low. +- The fix was guessed, not measured, and nothing got faster. +- Work cached outside the frame broke frame purity, so a render no longer matches its play. diff --git a/sdk/guides/craft/verbs/polish.md b/sdk/guides/craft/verbs/polish.md index 7fa14710..3757be75 100644 --- a/sdk/guides/craft/verbs/polish.md +++ b/sdk/guides/craft/verbs/polish.md @@ -9,5 +9,14 @@ redesign; if the direction itself is wrong, say so and go back to shaping. - Then the floor, line by line, on the last render. - Keep the strongest moment the critique named. +## Decide +- Polish or redesign. If the fixes add up to a new direction, stop and say so. +- Where to stop. When time is short, fix P0 to P2, and list the P3 items you left. + ## Verify - Render, look at the frames and open the whole export. Mark each critique issue fixed or say why not. + +## When it goes wrong +- Polish quietly changed the direction. +- The strongest moment was sanded down to match the rest. +- An issue was marked fixed without a new render to show it. diff --git a/sdk/guides/craft/verbs/quieter.md b/sdk/guides/craft/verbs/quieter.md index f13880a0..c46f1c45 100644 --- a/sdk/guides/craft/verbs/quieter.md +++ b/sdk/guides/craft/verbs/quieter.md @@ -8,6 +8,10 @@ note names. Keep the point of view: a quieter piece still has one. note's part or moment is where to start, but loudness usually comes from more than one place at once. - Name the one thing that should stay loud. A quiet piece still has one accent. +## Decide +- The one accent that stays loud. +- Take away or turn down. Removing a layer is cleaner than lowering everything a little. + ## Change - Take away before turning down: remove the second glow, the extra layer, the repeated whoosh. Then reduce what's left (intensity, saturation, speed, level) on the named part, not the whole frame. @@ -20,3 +24,8 @@ note names. Keep the point of view: a quieter piece still has one. ## Verify - Look at the same frames and moments as before, side by side. The note's part is calmer; the accent still lands. - Nothing outside the note changed unless it had to. + +## When it goes wrong +- It's lifeless: the accent went quiet along with everything else. +- The whole frame was desaturated or darkened, instead of the parts around the accent. +- Blur, fog or grain made it quieter by softening the work itself. diff --git a/sdk/guides/craft/verbs/recut.md b/sdk/guides/craft/verbs/recut.md index 2b2dfcc5..599040b0 100644 --- a/sdk/guides/craft/verbs/recut.md +++ b/sdk/guides/craft/verbs/recut.md @@ -9,6 +9,11 @@ of scenes and how shots join. - At each cut, check what joins the two shots: motion matched, a planned reversal, or a hard cut on a hit. A cut with no reason is a jolt. +## Decide +- The order the mode wants: the hook first in a pitch, one step after another in an explain, building to the poster + frame in a story. +- What each cut joins on: matched motion, a reversal, or a hit. Decide it before you move a shot. + ## Change - Move whole scenes, then re-time cues to the transcript. - Join motion to motion: a shot ends still moving and the next starts moving the same way. @@ -16,3 +21,8 @@ of scenes and how shots join. ## Verify - Watch every changed cut at full speed, then the whole piece. Nothing jolts that shouldn't. + +## When it goes wrong +- The cues are off after scenes moved: the words and the picture no longer meet. Re-time from the transcript. +- A jump cut no one planned, where two shots of the same framing sit side by side. +- The song is cut mid-phrase. Cut on its map. diff --git a/sdk/guides/craft/verbs/regrade.md b/sdk/guides/craft/verbs/regrade.md index b4f426a7..5abca504 100644 --- a/sdk/guides/craft/verbs/regrade.md +++ b/sdk/guides/craft/verbs/regrade.md @@ -8,6 +8,10 @@ light. - On the note's part, measure rather than guess: its colour temperature, brightness and saturation against what's around it. +## Decide +- What each colour means in this world, from the brief's `## Look`. +- Light or grade. When the scene can be re-lit or its materials changed, do that first. + ## Change - Change the light or the material in the scene before grading on top of it. A grade can't add what the light doesn't have. @@ -17,3 +21,8 @@ light. ## Verify - The same frames, before and after, side by side at the size it ships. In dark frames, check the export for blotching. + +## When it goes wrong +- Skin tones went off with the rest of the frame. +- The whole frame shifted, and the accent no longer stands apart. +- Blacks were crushed, and the dark frames blotch in the export. diff --git a/sdk/guides/craft/verbs/remix.md b/sdk/guides/craft/verbs/remix.md index eff1df5f..4a65ab3c 100644 --- a/sdk/guides/craft/verbs/remix.md +++ b/sdk/guides/craft/verbs/remix.md @@ -9,6 +9,10 @@ sound: voice, music, foley and the master. every entrance. - With a song, check the cuts and hits against its map. +## Decide +- What leads: the voice, or the music. Everything else sits under it. +- Which moments get a sound. A few marked moments beat a sound on every one. + ## Change - The voice first; duck music and foley under it. - Sound marks moments: a hit on the cut that matters, silence before the drop. Remove what only fills. @@ -17,3 +21,9 @@ sound: voice, music, foley and the master. ## Verify - Measure the loudness. Listen through once on small speakers and once on headphones. + +## When it goes wrong +- The voice is clear on headphones and buried on a phone's speaker. +- The music pumps as it ducks under the voice. Use a slower release, or a lower bed. +- Clipping, or a true peak over the limit. Measure, and don't trust the meter by eye. +- The loudness is off the delivery's spec. diff --git a/sdk/guides/craft/verbs/retime.md b/sdk/guides/craft/verbs/retime.md index 9ffc7f1b..23ddc054 100644 --- a/sdk/guides/craft/verbs/retime.md +++ b/sdk/guides/craft/verbs/retime.md @@ -8,6 +8,10 @@ and where the piece breathes. gone before it can be read, a cut before the result lands). - With music, look at the song's map: are holds and cuts on its beats, builds and stops? +## Decide +- The target length, from the brief or the delivery. +- Where the piece breathes: the one or two holds that earn their time. + ## Change - Fix it in the cut first: shorten the drags, extend the rushed. Motion can't rescue a slow cut. - Reading time: about 0.3 s a word, a second at least for anything that has to be read. @@ -16,3 +20,9 @@ and where the piece breathes. ## Verify - Watch it straight through once at full speed, without stopping. Mark anything that still drags or rushes. + +## When it goes wrong +- Every shot is the same length, so nothing feels faster or slower. +- Text is gone before it's read twice. +- The music is cut mid-phrase to make a hold fit. +- The piece is now longer than asked. diff --git a/sdk/guides/craft/verbs/typeset.md b/sdk/guides/craft/verbs/typeset.md index bad12129..6594f3d5 100644 --- a/sdk/guides/craft/verbs/typeset.md +++ b/sdk/guides/craft/verbs/typeset.md @@ -8,6 +8,10 @@ Notes like these: "I can't read it", "the font", "too small on my phone", "the c - Count the faces and weights. Name what each one is for (the brand's, from `brand/brand.css`; a caption's). - Check the measure: lines too long to take in at a glance, single words left alone on a line. +## Decide +- The face and weights, from the brand kit. A second face only when it has a job the first can't do. +- The sizes, from the smallest screen it plays on. + ## Change - One face, two at most, from the brand kit. Contrast comes from size and weight, not from more fonts. - Size for the phone: a 9:16 caption at least 48 px tall on a 1080 wide frame; titles far bigger. @@ -18,3 +22,9 @@ Notes like these: "I can't read it", "the font", "too small on my phone", "the c ## Verify - Stills of each line on a phone-size preview; read them aloud at speaking pace. - The faces in the render are only the ones the brand names. + +## When it goes wrong +- The render shows a fallback face because the font wasn't loaded. Check the faces in a still, not in the code. +- A single word sits alone on the last line. +- Captions sit over a face, or under a platform's buttons. +- A line is too long to read twice while it's up. diff --git a/skills b/skills index 261e8542..c5078601 160000 --- a/skills +++ b/skills @@ -1 +1 @@ -Subproject commit 261e854281fa8fe30e03a11ba07f43b8bbccc75d +Subproject commit c507860150995eb7c22ef9db23dee636c832428a