Guide

Write an agent brief that can fail closed

A useful brief is boring. It names the user-visible change, the files that are in bounds, the files that are out of bounds, and the command that proves the work.

Minimum fields

• Goal in one sentence — what a user can do afterward.
• Out of scope — refactors, dependency upgrades, and formatting sweeps are opt-in.
• Data rules — no production dumps, no real customer records in fixtures.
• Stop condition — when the agent must ask a human instead of guessing.
• Verification — exact test command and what “red” looks like.

Example shape

Goal: invoice list accepts cursor and limit. Out of scope: billing calculations. Stop if the existing pagination helper cannot be reused. Verify with the API test target and a manual empty-page case.

Paste that into your own agent. Then read the diff as if the agent is wrong. Use the brief builder if you want the fields formatted.