Skip to main content

Write a good task description

The description is the whole brief: the runner reads nothing else before it starts. A good one is short, concrete and says what done looks like. It does not have to be long — a few precise lines often deliver more than a page of background. These guidelines come from a hundred real tasks that went well; you can read them all, with what each one took, in Example tasks.

Write the description​

  1. Start with the goal and why it matters. One or two sentences a colleague would understand.

    When writing a very long ticket, losing it to an accidentally closed tab would be a disaster. Auto-save the input every few seconds without putting needless load on the server.

  2. Say where. Name the page, the tab and the control the way they appear on screen, and quote labels exactly.

    On the Clients page, select a client and open the Holdings tab. Filtering by ticker returns only exact matches.

  3. For a bug, give the symptom and what should happen instead. What you did, what you saw, what you expected. Paste the error or a screenshot rather than describing it.

    The ellipsis and plus icons should only appear on hover. After I click a project, they stay visible until I click somewhere else.

  4. Show it. Paste a screenshot or a mockup straight into the description, or select Attach, and point at it in the text ("see the attached screenshot"). A picture of the screen settles most layout questions before they are asked.

  5. List the requirements, one per line. Numbered items or bullets, each a single thing to check. Give exact values where they matter: names, defaults, limits and who can see what.

    • Add an Assigned To field to the right of Attach. Initial value: the user who creates the task.
    • When Assigned To changes, notify the new assignee.
    • Assigned To can be changed even after the task is done.

  6. Say what done means. One line the result can be checked against.

    Definition of done: several copies of the service run at once and every feature still works.

  7. Set the boundaries. Say what not to touch with an "Out of scope" line, and say so when you want advice instead of code ("Don't change the code; just prepare the report").

  8. Ask for options when you are unsure. "Suggest three options before implementing" or "What do you recommend?" gets you a choice to make instead of a guess you have to undo.

  9. Pick the size that fits. Sketch for a mockup to look at, Task for one change, Epic for an ask with several parts that should be analysed and split first. See Start a task.

Check it before you select Go​

  • Could someone new to the project do it from this text alone?
  • Does every requirement say what, where and how much?
  • Is there a line that says what done means?
  • Have you removed what you don't want built? Anything extra in the description is work the runner will do.

If you choose Guided, the runner asks before key decisions, so a gap in the description becomes a question rather than a guess. How to reply is in Answer a task's question; what came back is in Read a task's result.