Task status workflow
Every status a task can have, and every move between them: who makes it and what it needs.
Sparrow allows any move and records who made it (see Who moves a task).
This page is the workflow that agents and the landing automation follow; people can depart from it.
It follows laws feature-branch-per-ticket 5.0.0 and
ticket-batches-land-one-pull-request-at-a-time 3.0.0, Sparrow's ADR-0018, ADR-0025 and
ADR-0026, and the repository's root ADR-0010; the laws rule where they differ. Sparrow's
ADR-0027 records why it is written this way.
Statuses
| Status | Meaning |
|---|---|
| Planning | Filed: a person has stated the intent, not yet ready to start |
| Refining | The agent has written its brief-back and draft plan, and asks its questions on the task for you to answer |
| Queued | Every question is answered: ready for someone to pick up. Answering the last open question of a Planning or Refining task moves it here |
| In Progress | Someone is working on it |
| Reviewing | The work is handed back for a person to review: its pull request is open |
| Completed | The work landed and every post-merge run on its merged commit succeeded. Normally the landing automation moves a task here |
| Cancelled | It won't be done |
| Blocked | It can't go on: it waits on something outside the task or on the answer to a question raised once work started, or a check failed (a post-merge run on its merged commit, or a check on its pull request when a person dismissed the review). Its summary says which |
The workflow
Each arrow is a move, labelled with who makes it. GitHub draws the diagram; elsewhere it reads as text, and the table below says the same.
flowchart LR
filed(["Filed"])
subgraph open ["Any open status"]
planning["Planning"]
refining["Refining"]
queued["Queued"]
in_progress["In Progress"]
reviewing["Reviewing"]
blocked["Blocked"]
end
completed["Completed"]
cancelled["Cancelled"]
filed -->|Person or agent| planning
planning -->|Assignee| refining
planning -->|Assignee, person or Sparrow| queued
planning -->|Assignee| in_progress
refining -->|Assignee, person or Sparrow| queued
refining -->|Assignee| in_progress
queued -->|Assignee| refining
queued -->|Assignee| in_progress
in_progress -->|Assignee| blocked
blocked -->|Assignee| in_progress
in_progress -->|Assignee| reviewing
reviewing -->|Landing automation or person| completed
reviewing -->|Landing automation| blocked
blocked -->|Assignee| reviewing
blocked -->|Landing automation or person| completed
open -->|Person| cancelled
Moves
Who is one of:
- Assignee: whoever works the task, an agent or a person.
- Person: a member deciding, such as the requester, the reviewer or the owner. An agent acts here only on a person's word.
- Agent: any agent filing a task, whether a person asked for it or it found the need itself.
- Sparrow: the tracker itself.
- Landing automation: a repository's machine credential, which lands pull requests whose review a person dismissed and checks the runs on every merged commit (ADR-0018, ADR-0026, root ADR-0010). Where a repository has none, the person moves the task.
| From | To | Who | When |
|---|---|---|---|
| Filed | Planning | Person or agent | Filed with the intent in the description; an agent says whether it is directed |
| Planning | Refining | Assignee | The brief-back (and, under a planning check, the draft plan) is written. Under a planning check this move is always made, and then the assignee asks every question; otherwise it is made when the work waits on an answer |
| Planning | Queued | Assignee, person or Sparrow | Sparrow: the last open question was answered, recorded as the answering person's move (ADR-0025). Assignee: no planning check, brief-back written, not starting now. Person: accepts the brief-back |
| Planning | In Progress | Assignee | No planning check, brief-back written, and no open question the work depends on |
| Refining | Queued | Assignee, person or Sparrow | Sparrow: the last open question was answered, recorded as the answering person's move (ADR-0025). Assignee: no planning check, every question the work depends on answered, not starting now. Person: every question answered; moving it accepts the brief-back. Under a planning check an agent moves it only on the person's word |
| Refining | In Progress | Assignee | No planning check, and every question the work depends on is answered |
| Queued | Refining | Assignee | A question is unanswered, or a new one comes up before work starts |
| Queued | In Progress | Assignee | Picked up; under a planning check, every question is answered |
| In Progress | Blocked | Assignee | A question the work can't go on without (a planning failure: the assignee asks it on the task with ask_question and names it in the summary), or something outside the task it waits on. The summary says what; a blocking task gets a blocks edge |
| Blocked | In Progress | Assignee | The question is answered or the cause is gone |
| In Progress | Reviewing | Assignee | The pull request is open and recorded (pull_request_url), and the ## Debrief is written |
| Reviewing | Completed | Landing automation or person | Merged with "Rebase and merge", and every post-merge run on the merged commit succeeded. Without the automation: the person who landed it, or an agent holding the owner's written grant for the task or batch |
| Reviewing | Blocked | Landing automation | A post-merge run failed, was cancelled or timed out. When a person dismissed the review, also a failed check on the pull request |
| Blocked | Reviewing | Assignee | A fix for a failed pull request check is pushed |
| Blocked | Completed | Landing automation or person | A re-run of the failed workflow succeeded, or a person closes the task once it is fixed |
| Any open status | Cancelled | Person | It won't be done. The summary says why; a duplicate gets a duplicates edge |
Rules
- A person can make any other move by hand: a shortcut, a correction, reopening a task. Sparrow allows every move and records who made it.
- Agents and the landing automation make only the moves in the table.
- Completed and Cancelled are final for agents and the automation.
- Review changes keep the task in Reviewing: there is no move from Reviewing back to In Progress.
- The landing automation acts whatever open status the task is in: it completes or blocks a merged task, and blocks one whose review a person dismissed when a check on its pull request fails. The table shows where it normally finds the task.
- Under a planning check, the assignee moves the task to Refining first and then asks every question (ADR-0025).
- A question raised once the task is In Progress is a planning failure, and moves the task to Blocked, not Refining. The assignee asks it on the task and names it in the summary.
- Blocked is the assignee's for work that has started: the task returns to In Progress, or to
Reviewing once a failed pull request check is fixed. A task that hasn't started stays in its
column, with a
blocksedge to what it waits on. - Only a person cancels a task, and the summary says why.