> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bellows.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Writing good tasks

> The agent knows your code only through the repo and your words. Be specific about the outcome and how to verify it.

## Principles

* **Say what “done” looks like.** An endpoint, a behaviour or a failing test that should pass.
* **Point at the place.** File, package or function names save the agent's exploration time.
* **One change per task.** Split unrelated work; follow-ups are cheap.
* **Let gates verify.** Don't ask for “make sure tests pass”; gates already enforce that.

## Good vs bad

> [card] Vague
>
> `Improve the notes API.`
>
> No outcome, no scope. The agent will guess.

> [card] Specific
>
> `POST /api/notes should return 400 when title is empty or over 200 chars. Add cases to server_test.go.`
>
> Clear behaviour, location, verification.

> [card] Bundled
>
> `Add pagination, fix the lint warnings and rename lorem to text.`
>
> Three reviews in one PR.

> [card] Focused
>
> `Add ?limit and ?offset to GET /api/notes (default 20, max 100).`
>
> One PR, easy to review.

## Checklist

* [ ] Outcome stated in one sentence
* [ ] Files or packages named
* [ ] Edge cases or limits spelled out
* [ ] Screenshot or spec attached, if the change is visual

**Worked example:** [Fix a bug from a Jira ticket](https://docs.bellows.cloud/use-cases/fix-jira-bug.md), [Add tests to a package](https://docs.bellows.cloud/use-cases/add-tests.md), [Upgrade a dependency](https://docs.bellows.cloud/use-cases/upgrade-dependencies.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.