Writing a brief
How to write a brief an agent can finish
Name the change you want. State how you'll know it's done. Say where it lives.
- 87.6%
- Stories that cleared every gate on the first pass
- $9.38 → $28.43
- Mean cost: clean run vs. review sent it back
- 42.5 min
- Median time from brief to merged
From "Anatomy of an $8 feature" (20–26 July 2026, n=944).
What a brief is
A brief has three parts
Everything else is detail. Get these three right first.
What you want
Say what should exist once the work is done. A fixed layout. A new field. A passing test. Name the outcome plainly.
How you'll know it's done
State the check a person can run once the change lands. See acceptance criteria for the exact term.
Where it lives
Name the page, the file, or the repository the change touches. For the exact steps to file it, see writing tasks.
Why the brief is the cheapest lever
Rework costs more than a clean run
CodeHerder's own production data groups every shipped story by which gate sent it back, if any.
| Outcome | Share of stories | Mean cost | Median time to merge |
|---|---|---|---|
| Clean run, no gate fired | 87.6% | $9.38 | 42.5 min |
| Review sent it back before merge | 9.9% | $28.43 | 194.2 min |
| Verify sent it back after merge | 1.7% | $26.78 | 321.2 min |
| Both gates sent it back | 0.8% | $54.40 | 347.9 min |
This groups stories by which gate caught a problem. It does not grade the brief that started each story. Rework costs more than a clean run does. That holds for cost and for time. The brief is the one part of the work a person controls before any stage runs. See the full numbers in the receipt post.
Six checks a brief should pass
Run your brief through these six checks
Each check names a rule, then shows a weak phrasing next to a stronger one.
Name the change someone can see.
A concrete symptom gives both the agent and the reviewer one visible target to check against.
WeakThe button looks bad on mobile.
StrongerThe button near the top of the phone screen gets cut off. You cannot tap the whole thing.
Say where it shows up.
Naming the exact screen or file bounds the search. Without it, the agent has to guess which of many places to change.
WeakAdd a field for it.
StrongerAdd the field to the signup form, near the other contact fields, and show the saved value on the profile page.
Write the check before the work.
A test that fails on the old behavior and passes on the fix gives you proof the fix works.
WeakMake sure this bug doesn't come back.
StrongerWrite a test that fails on the old broken behavior and passes once the fix is in place.
Keep it to one merge.
A brief scoped to one change gives the reviewer a diff they can read start to finish.
WeakUpdate the dependency, and clean up the config files while you're at it.
StrongerUpdate this one dependency to this version. Fix whatever it breaks.
Say what must not change.
An invariant gives the reviewer one clear thing to check the diff against.
WeakClean up the duplicated code.
StrongerMerge the duplicate logic into one place. Keep every call site behaving exactly as it does today.
Hand over the evidence you already have.
Pointing straight at the drifted feature saves the agent a whole investigation pass.
WeakThis doc page seems out of date.
StrongerThis doc page describes a feature that has since changed. Check each step against how it behaves today.
How to say done when you cannot read code
State it as what you click, and what you then see
You do not need to read a diff to write a good check. Say what you will click. Say what should happen next.
A bug
- Open the page on a phone. Look at the control that was cut off.
- Tap the control, edge to edge. It responds.
- Open the same page on a laptop. It looks the same as before.
A small feature
- Set the filter. Only the matching rows show.
- Clear the filter. The full list comes back.
- Page through the filtered results. Paging still works.
A docs fix
- Copy the example from the doc page. Run it.
- Watch it finish with no error.
- Read the paragraph around it. It still matches what the example does.
Matching brief: "A code example in the docs no longer runs" →
Test coverage
- Run the test suite. The new tests pass.
- Ask someone to break the file's behavior on purpose. The new tests fail.
What to leave out
Five things that make a brief harder to finish
Dictated implementation
State the outcome. Let the agent choose how to build it.
Two jobs in one brief
One brief, one job. Split a second job into its own brief.
"Make it better"
Name a concrete outcome. "Make it better" gives the agent nothing to check against.
An invented API
Ground the brief in what exists today. A method or endpoint that doesn't exist yet gives the agent nothing to call.
A deadline
State the outcome you want. A time limit doesn't change what "done" means.
The checklist
Copy this before you write your own
Paste this above your own brief. Check each line before you file it.
Copy this and file it as a task
Before I file this, my brief: 1. Name the change someone can see. 2. Say where it shows up. 3. Write the check before the work. 4. Keep it to one merge. 5. Say what must not change. 6. Hand over the evidence you already have.
Now file one
Copy a brief, or read one that already shipped
Copy a ready-to-file brief at /starter-briefs. Read real briefs that already merged at /examples.
FAQ
Questions people ask before filing their first brief
Do I need to know how to code to write a good brief?
No. Say what you want and how you will check it. Then say where it shows up. See "How to say done when you cannot read code" above for four patterns you can copy.
How long should a brief be?
As short as the six checks allow. Name one visible change and one check. That is usually enough for a whole brief.
What if I don't know the exact file or screen?
Name what you do know: the symptom, the page, or the feature. The plan stage locates the exact file before any code is written.
Can one brief cover more than one change?
Keep it to one job per brief. File a second brief for the second job, so each one stays a single merge a reviewer can check.
Write the brief. We'll run it.
File a task the way this page describes, and an agent plans it, builds it, then opens a pull request.