Writing task briefs with acceptance criteria

In Module 1 you wrote a four-part brief: goal, context, a “done when” check, and a “don’t” line. That works for small tasks. For anything bigger, the part that makes or breaks the result is the “done when”, and it deserves more care.

A brief is a contract. The acceptance criteria are the clauses you can actually enforce.

Anatomy of a brief

Not every brief needs all six at full length. A small task can have one line per part. But when a result disappoints me, I can almost always trace it to a missing part, usually 4 or 5.

What makes a criterion checkable

A good acceptance criterion is something either you or the agent can verify without asking anyone. The best ones are a command with an expected result. The next best are observable behavior. The worst are adjectives.

Notice the right column names the edge cases instead of hoping the agent guesses them. Writing them down is also how I find out I hadn’t decided what should happen.

A full brief

Goal
Add CSV export to the orders report so finance can stop copy-pasting
from the screen.

Context
- Report endpoint: src/api/reports/orders.ts
- Follow the existing PDF export in src/api/reports/pdf.ts for structure
- CSV helper already exists: src/lib/csv.ts

Constraints
- No new dependencies
- Reuse the report's existing query; don't write a new one

Acceptance criteria
- GET /reports/orders/export?format=csv returns text/csv
- Header row matches the columns shown on screen, same order
- Empty range → header-only file; range > 366 days → 400 with a message
- New tests cover these three cases; full test suite passes
- Linter and type checker pass

Out of scope
- The UI button (separate task)
- Changing the PDF export

Report back
- Files changed, and any decision you made that isn't in this brief

Check yourself

🧠 Briefs and acceptance criteria

Score: 0 / 4

1. 1. Which acceptance criterion is the most checkable?

   The page loads quicklyThe code follows best practicesThe new endpoint returns 404 for an unknown ID, covered by a testErrors are handled properly

   It names a specific input, an expected output and how it’s verified.

2. 2. Why include an “out of scope” section?

   To make the brief longerAgents tend to “helpfully” improve nearby code, which bloats the diffIt’s required by most agentsTo list future work for the backlog

   Naming what not to touch keeps the diff small and reviewable.

3. 3. You can’t write a checkable criterion for a task. What does that usually mean?

   The agent will figure it outThe task isn’t well understood yet, so clarify or split it firstYou should skip criteria for this oneYou need a bigger model

   If you can’t say what done looks like, the agent can’t either.

4. 4. What’s the point of asking the agent to report decisions that weren’t in the brief?

   To fill the final messageTo surface choices you’d otherwise only find by reading every lineTo test the agent’s memoryThere’s no real point

   Unstated decisions are where surprises hide. Make them visible.

↺ Try again

Before you move on

✅ Key takeaways

0 / 4 completed

• My briefs have a goal, context, constraints, acceptance criteria, out of scope and report back.
• My acceptance criteria are observable and, where possible, a command with an expected result.
• I name edge cases in the criteria instead of hoping the agent guesses them.
• I use the same criteria as my review checklist when the diff comes back.

↺ Reset