A useful brief for a coding agent names the current failure, the behaviour you want and how to check it. It also says what the agent should leave alone.
That sounds obvious until you write "fix authentication" and get a new login screen, a different session store and a migration you did not ask for.
The agent had a large space in which to be right. Your actual problem occupied one corner of it.
01what should the brief say first?
Describe a thing somebody can do. Say what happens when they do it.
"Signing in with the wrong password leaves the submit button spinning" gives the agent somewhere to start. "Improve the login experience" gives it a design project.
If you know the route, include it. If you have a failing command or an error message, paste it exactly. If you do not know the file that causes the failure, leave that discovery to the agent.
A guessed path can send a good investigation in the wrong direction.
02what does a useful acceptance check look like?
For the spinning button, the answer might be:
On
/login, a wrong password shows an error beside the password field. The button becomes usable again. The email stays in the field. A correct password still signs the person in.
That paragraph is an acceptance check. A reviewer can open the page and decide whether the change did it.
It also exposes choices hidden in "fix authentication". Should the field clear? Should the error reveal whether an email exists? Does a retry require refreshing the page?
Decide the behaviour you care about. The agent can decide how to implement it inside the repository's conventions.
03how do you stop a small fix becoming a rewrite?
Add a boundary when a plausible fix could become a larger change:
Keep the current authentication provider and session format. This job does not change registration or password reset.
A boundary earns its place by preventing a likely detour. A page of prohibitions makes the actual job harder to find.
For a change that needs new dependencies, a migration or a deploy, say whether those are part of the request. A pull request that fixes the screen and requires an unplanned database change has created another job.
04where should the brief live in Wayari?
Wayari puts a job into a channel and gives its agents written tasks. Each shift starts fresh. The acceptance check needs to live in the goal, where the next builder and the reviewer can read it.
Use the same words you would use with your own agent:
wayari start "On /login, a wrong password must show an error, stop the spinner and allow retry. Keep the email and current auth provider. Check that a correct password still signs in." --repo ~/code/app
The first-channel documentation walks through starting a job. The command creates work; it does not authorize every later act a builder might want.
05what evidence should you ask the agent for?
A unit test can prove that a function returns the right error. Opening the page proves that a person can see that error and retry.
Ask for both when both matter. For a command-line bug, ask the agent to run the failing command and show its output. For an export bug, ask it to inspect the exported file.
Keep the proof attached to the behaviour. "Add tests" can be satisfied by tests that never reach the defect.
There is more on that distinction in a green test suite never opened the page.
06what changes between a vague and a usable brief?
The difference is something another person can check without asking what you meant.
| Vague request | Checkable replacement |
|---|---|
| Fix authentication | A wrong password shows an error and lets the person retry. |
| Add tests | Reproduce the failed login and keep a test that fails on the old behaviour. |
| Clean up while you are there | Keep the provider and session format. Leave registration and reset alone. |
07what if the goal is still vague?
Give the agent an investigation first. Ask it to reproduce the failure, identify the cause and propose the smallest fix. That has a finish line even when the implementation does not.
Once the problem is named, turn the proposal into a bounded job.
The useful question before you submit is: could somebody who missed this conversation tell whether the pull request finished the work? If the answer depends on what you meant, put that part in the brief.
08do you need to name every file?
No. Include a path you have verified when it helps the agent reproduce the failure. Leave uncertain paths out and ask for an investigation first. The repository instructions guide covers boundaries that apply to every job.
