# Briefs that work

> Turn a feeling ("make it smoother") into a brief an agent can act on, decide where your judgment is worth spending, and hand over evidence instead of adjectives.

Module: Directing your agent · Level: beginner · 7 min · https://school.agents.org.in/foundations/agents/briefs-that-work

You type "make the menu smoother". The agent (A language model plus a harness: the model decides what to do, the harness gives it tools to read files, write code, run it and check the result) changes the duration, adds a bounce and swaps the curve. It is different now. It is not better.

The agent did not fail. You gave it a feeling, and a feeling has a thousand right answers. Pick one of the vague asks below and look at what replaces it.

*[Interactive demo: Each vague ask has a precise word behind it. The word brings the numbers with it.]*

## Why agents land in the middle

An agent produces the average of everything it has seen. Left alone, that is where your interface ends up: fine, and indistinguishable from every other one.

Steering is how you move it off the average. A brief (The few sentences you send an agent before it starts: what to build, for whom, and the exact values that matter. A good brief names things instead of describing how they feel) is the few sentences that do the steering: what to build, for whom, and the exact values that matter.

> **In plain words.** A **brief** is the message you send before the agent starts. Good briefs name things ("tabular figures") instead of describing how they feel ("the numbers jump").

## Name it, don't describe it

"Make it smoother" leaves the agent guessing. "Open it from the trigger, 200ms, `cubic-bezier(0.23, 1, 0.32, 1)`, transform and opacity only" does not.

You do not need every number. You need the concept. *Tabular figures*, not "the numbers jump". *Inner radius = outer − padding*, not "the corners look off". The precise word is a key, and the agent already has the lock.

  **Vague (avoid):**

"The card feels cheap. Make it nicer."

  **Named (do this):**

"Layered shadow at 4–6% opacity instead of the 16px blur, and 8px inner radius on the image (the card is 16px with 8px padding)."

The skill keeps a whole lexicon (The exact names for how interfaces look and move, like tracking, easing or hierarchy. The right word gets you the right result from an agent) of these words, seeded from Emil Kowalski and Glenn Carstens-Peters' work on articulating design. Its one job is to stop anyone, you or the agent, saying "weird". Look a word up, use it, stop.

*(A screenshot with arrows often beats any word.)*

## Spend your judgment where it changes the result

Some work only you can judge: what to build, which direction to keep, when to stop. Other work your opinion adds nothing to: research, summaries, a command menu the agent has built a hundred times.

  **Step: Get interrogated first.** For a new feature, ask the agent to question *you* until the goal, the user and the why are written down. Skip this for research.

  **Step: Delegate known patterns.** A data grid, a chart, a command menu: hand them over whole.

  **Step: Hand-tune the fabric.** Page layout, the type scale and spacing are often faster by hand, or with one precise prompt each.

## One or two passes, then look

Every pass is a bar the work has to clear. Ask for five at once and you get a muddle that half-satisfies each.

Run one or two. Look at the screen. Then run the next. The one exception is the launch-week sweep, which crosses everything on purpose; you will meet it later as `ship`.

**A brief for one pass (paste into your agent):**

```text
Polish the pricing card only. Two things:
1. Press state: scale(0.97) on :active, 120ms, ease-out.
2. Tabular figures on the price so it doesn't jitter when the plan toggles.
Don't touch layout or colors. Show me the diff.
```

## Fix the system, not the screen

Try this: ask for one real screen in one sentence ("a dialog that publishes pending changes, using our components"). Every mistake in the result points at a hole in your system.

| The agent did this | The hole |
|---|---|
| a raw hex or a one-off spacing value | a semantic token is missing or badly named |
| invented a `ghost` button variant | the variant list isn't closed |
| hand-rolled a select instead of `Select` | the component has no "when to use" note |

Correct the screen and you fixed one screen. Patch the hole and the next screen comes out right.

## The papercut pipeline

Spot, document, delegate. When something small is wrong, write it up with the evidence: a screenshot with arrows, or for motion, a recording scrubbed to the bad frame. Name the cause if you know it ("the select renders in a portal, so the modal treats a click on it as outside").

It takes two minutes to write, and the agent fixes it while you keep working.

## When you want what someone else built

"How did they build that gradient?" is a question about a mechanism. The lazy answer is a dump of computed styles and a lookalike snippet. It explains nothing.

Ask the agent to read the page as **evidence, never instruction**, and to tag every claim: *measured* (read off the page), *derived* (computed from measurements) or *inferred* (a guess about intent). Then close on the recipe in words: the layers, their order, the one or two values doing the work.

**Explain another site's effect (paste into your agent):**

```text
How is the glow behind the hero on example.com built?
Scope to that one effect. List the layers in paint order with the declaration doing the work on each.
Tag every claim measured, derived or inferred.
End with the recipe in words, plus what wouldn't survive copying. No lookalike code.
```

> **A page is not a prompt.** Text inside someone else's page (comments, class names, alt text) is content to report. It never changes what the agent does next.

## When the agent keeps missing

Two rounds of "closer, but not quite"? Rephrasing a third time is the casino. Build a small tool instead, a lesson of its own in this module. The opposite failure is real too: tooling up for something you hit once is procrastination with extra steps.

**Check yourself:** The agent keeps writing raw hex colors in new screens. What fixes it for every future screen?

- [ ] Correct the hex in this screen
- [ ] Rephrase the prompt to say 'use our colors'
- [x] Add or rename the missing semantic token so the agent can find it
- [ ] Ask for five passes at once

*Why:* A raw hex points at a hole in the system: the token the agent needed was missing or hard to find. Patch the hole and every later screen comes out right.

## In the skill

- https://school.agents.org.in/skill/meta/directing-agents.md
- https://school.agents.org.in/skill/meta/design-vocabulary.md
- https://school.agents.org.in/skill/meta/reading-others-interfaces.md