Skip to main content

Write issues an agent can finish

An agent finishes an issue when it knows what to change, where, and how to tell it is done. Write the issue the way you would for a new teammate who can read the code but was not in your planning meeting.

Include these four things​

  1. The outcome. What should be true when the work is done, in one or two sentences.
  2. Where. The repository, and the screen, endpoint, module or file area if you know it.
  3. How to check it. The acceptance criteria: what a reviewer should see, and which tests or commands prove it.
  4. Context. Links to related issues, designs, error logs or earlier pull requests. The agent reads linked Linear issues.

Template​

## Goal
Show a clear message when an export has no rows, instead of an empty file.

## Where
Repo: acme/web-app
Base branch: main
Export button on the Reports page (src/features/reports).

## Acceptance criteria
- An empty export shows "Nothing to export for these filters".
- A non-empty export still downloads a CSV.
- Unit tests cover both cases.

## Context
Reported in ACME-412.

The Repo: and Base branch: lines are only needed when your workspace allows more than one repository, or when the target is not obvious. Without them, the agent asks.

Keep it to one pull request​

Good first tasks are changes a reviewer can check in a few minutes. A run stops after 5 hours, so split large work into several issues and connect them as blocking issues in Linear. Issues picked up through the Automatable label wait until the issues blocking them are done.

Make review possible​

The review run checks the pull request against what the issue asks for, so vague criteria make for vague reviews. Name the behavior to verify, not just the code to touch. "Fix the export" gives the reviewer nothing to check. "Empty exports show a message and tests cover it" does.

Mind the hashtags​

Any #word that matches an alias, such as #sol, chooses that agent. Use aliases on purpose. See Choose an agent with aliases.

When the agent asks​

If something is missing, the agent asks in the Linear thread and waits. Answer there. The clearer the issue, the fewer questions you get.