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.
- 60.8%
- Stories that cleared every gate on the first pass
- $9.02 → $26.55
- Mean cost: clean run vs. sent back before merge
- 63.6 min
- Median time from brief to merged
Measured across 355 shipped stories, the week of 21–27 September 2026.
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. Put it in the Title and Description fields of the New task form.
How you'll know it's done
Write each check a person can run as one
- [ ]line in the Acceptance criteria field. See acceptance criteria for the term.Where it lives
Pick the repository in the Repos picker. Name the page or file in the Description. For the steps to file it, see writing tasks.
A story needs at least one - [ ] line before it can leave plan. Every line must be ticked before the task can merge. A check that only works on the live site starts with (proof: verify). That check can wait until after the merge. Read the full rules.
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 | 60.8% | $9.02 | 63.6 min |
| Sent back before merge | 35.5% | $26.55 | 99.8 min |
| Verify sent it back after merge | 1.1% | $19.74 | 229.9 min |
| Sent back before and after merge | 2.5% | $70.32 | 869.4 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. The receipt post explains the method.
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. Paste your own brief into the brief checker and try it against all six.
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.
Put each check in Acceptance criteria as a - [ ] line. This example uses the bug pattern. The last line starts with (proof: verify), so it waits until the change is live.
Copy this and file it as a task
- [ ] 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. - [ ] (proof: verify) The fix works on the live site.
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 template into the New task form. Fill the Description first. Put the checks in Acceptance criteria.
Copy this and file it as a task
Description: What is wrong, and where. Name the page or screen. What must not change. Acceptance criteria: - [ ] The first thing I will check, and what I will see. - [ ] The second thing I will check, and what I will see.
Before you file, read your brief against the six checks above. Do not paste them into the task.
- Name the change someone can see.
- Say where it shows up.
- Write the check before the work.
- Keep it to one merge.
- Say what must not change.
- 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.
Is a bug brief different?
Yes. Pick the Bug type. A bug starts with triage, not plan. It asks for steps to reproduce in the Reproduction field. List what you click and what you see.
What if my brief is unclear?
The agent asks you a question. You answer it in the web app. The agent usually pauses until you answer. A short note from the agent does not stop the work.
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 Story the way this page describes. A planning agent writes the plan. A build agent opens a pull request. Review and merge agents land it. A verify agent checks the change in the live app.