Working on a task

How a task's description, summary, questions, cost and work plan are used from filing to completion.

A task carries two pieces of writing:

  • The description belongs to whoever asked for the work, in markdown. It gives the context, why the work matters and the acceptance criteria.
  • The summary belongs to the assignee, in markdown. A new task's summary is empty.
    • When you pick a task up, write a ## Brief-back in the summary: the requester's instructions, their intent and your plan, in your own words. The requester can then catch a misunderstanding before the work starts. Move the task to In Progress when you start the work (see planningRequiresValidation under Effort and validation).
    • When you open the task's pull request, record it on the task with update_task (pull_request_url and pull_request_title, the pull request's title). The task's page shows it as a link under Pull request; you can also set or clear it in Edit.
    • When the work is done, keep the brief-back and add a ## Debrief below it: what was done, anything that blocked you, and friction worth fixing later. Then move the task to Reviewing.

When a task isn't clear enough to work, an agent asks you on the task, with the MCP tool ask_question, instead of guessing. Its questions show on the task's page, each with a form to answer it there, without opening Edit:

  • A text question takes a written answer.
  • A choice question takes one choice and an optional note. Its constraints can change that: multiple-choices-valid allows several choices, and zero-choices-valid allows none.

Answers are final: Sparrow records who answered and when, and the agent reads them on the task (ADR-0021).

When you answer the last open question on a task in Planning or Refining, Sparrow moves it to Queued, recorded as your move; that accepts the agent's brief-back. A task already In Progress or later stays where it is (ADR-0025).

Sparrow records every status a task moves into, with when and by whom. Once a task is Completed, its page shows a timeline: the time from creation to completion, and how long it spent in each status.

Every move between statuses, who makes it and what it needs is in the task status workflow. One rule belongs here: a question the work can't go on without, once the task is In Progress, moves it to Blocked, not back to Refining. Ask it on the task with ask_question, name it in the summary, and move the task back to In Progress once it's answered.

A task also records its cost: the tokens its work used, and their price when it's known, with one row per provider, model line and model version (for example anthropic, opus, 5.5). Adding the rows up by model line compares Opus with Sonnet; adding them up by version compares Sonnet 5.5 with 5.6. Agents record each work item's usage with the MCP tool record_work_item (below), and any work outside the plan with record_cost, once per model, whenever they finish it. Once a task is Completed, its page shows the cost as a table by model, with the total, and as a pie of each model's share of the tokens when more than one model worked on it.

For every task, the session delegates the planning, the high-effort pieces and the review to a separate agent on the high-effort model, and the other pieces to cheaper agents. It records the work plan on the task: the ordered work items (planning is the first), each with a one-sentence summary, the agent definition that does it, its model, and the earlier items it waits for. As each item finishes, the session records the item's time, tokens and price with the MCP tool record_work_item, which also adds them to the task's cost, so the cost stays the total; record_cost is then only for work outside the plan. The task's page shows the plan as a table with each item's results, and the cost pie gets one slice per work item, shaded by its model (ADR-0019).