Guide · task brief

The 4-line task brief

Updated 27 October 2026

A good task brief fits in four lines. Say what the goal is, where it goes in the app, how to check it is done and what to leave alone. The agent then has less to guess. You get a small pull request that is easy to review.

The brief works with any AI coding agent, and with people too. Copy it below. The notes after it say why each line is there. The Keelen notes at the end say what Keelen does with a brief like this.

Copy the brief

Fill in each line. Keep it to one change.

Goal: [One sentence. What is true when this is done?]
Where: [The page or screen. Add the file path if you know it.]
Done when: [Two or three things you can see or test.]
Leave alone: [What must not change.]

A filled-in example

A small change to a made up invoice app.

Goal: Users can sort the invoice list by due date.
Where: The Invoices page, in the table header (app/invoices/page.tsx).
Done when: Clicking "Due date" puts the oldest first. A second click puts the newest first. The order stays after a page refresh. A test covers both orders.
Leave alone: The invoice API and the database. Add no new packages.

Why each line matters

Goal: one change, one result
Say what a user will see when the work is done. Describe the result, not the code. One goal per brief keeps the pull request small enough to read in one sitting.
Where: point at the spot
Name the page or screen. Add the file path if you know it. Then the agent does not have to guess which part of the app you mean, and the change stays in one place.
Done when: a finish line you can check
List two or three things you can see or test. Each one can turn into a check, so you and the agent agree on what done means. If the goal is about speed or size, give a number. With no finish line, the agent has to guess or ask you.
Leave alone: no surprises in the diff
Name what must not change. That might be other pages, the database, the API or the list of packages. A small diff with no surprises is the one you can review and merge.

Common mistakes

Two changes in one brief
"Fix the login bug and add dark mode" is two jobs. Each one needs its own review. Send two briefs.
A finish line nobody can check
"Make search faster" or "make it look better" has no end. Say what done looks like, such as "results show in under one second".
No line about what to leave alone
Then the agent may tidy up code you did not ask about. The diff grows, and the real change gets harder to find.

When a brief is not enough

You do not know yet what you want. Talk it through or sketch it first. A brief is for work you can already describe.
The change is big, like a redesign or a new part of the app. Split it into small briefs, one change each.
You cannot say how you would check it. Then the work is not ready to hand off, to an agent or to a person.

Where Keelen fits

Keelen is an AI coding agent for GitHub repos. You send it work as a Request in plain words. A brief like this one makes a good Request. Here is what happens to it.

Your brief turns into tasks

An intake pass sorts each Request. It becomes a roadmap item, a question for you or a steering rule. Each roadmap item then turns into tasks. Each task gets acceptance criteria, the checks that say it is done. A clear "done when" line gives those checks a real place to start.

It asks instead of guessing

If a Request is too vague to build, it comes back as a question. Once you answer, planning goes on with your answer.

Checks on the result

If your project has a test command, new tests must fail without the change first. Tests that pass from the start are rejected. A separate review run reads the diff. It does not see the run that wrote the code. Nothing merges over a red required CI check.

You pick what can merge

Each project has a merge setting. Gated auto merge is the default, so pick manual merge for your first briefs. Then Keelen opens the pull request and you click merge. Plan review is a separate opt in. When it is on, a person approves the plan before any code is written.

Approval before merge →

Try it on one small task

Connect a GitHub repo and an AI account, and pick manual merge. Then send one brief as a Request and review what comes back.

Get started