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

StatusMeaning
PlanningFiled: a person has stated the intent, not yet ready to start
RefiningThe agent has written its brief-back and draft plan, and asks its questions on the task for you to answer
QueuedEvery question is answered: ready for someone to pick up. Answering the last open question of a Planning or Refining task moves it here
In ProgressSomeone is working on it
ReviewingThe work is handed back for a person to review: its pull request is open
CompletedThe work landed and every post-merge run on its merged commit succeeded. Normally the landing automation moves a task here
CancelledIt won't be done
BlockedIt 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.
FromToWhoWhen
FiledPlanningPerson or agentFiled with the intent in the description; an agent says whether it is directed
PlanningRefiningAssigneeThe 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
PlanningQueuedAssignee, person or SparrowSparrow: 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
PlanningIn ProgressAssigneeNo planning check, brief-back written, and no open question the work depends on
RefiningQueuedAssignee, person or SparrowSparrow: 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
RefiningIn ProgressAssigneeNo planning check, and every question the work depends on is answered
QueuedRefiningAssigneeA question is unanswered, or a new one comes up before work starts
QueuedIn ProgressAssigneePicked up; under a planning check, every question is answered
In ProgressBlockedAssigneeA 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
BlockedIn ProgressAssigneeThe question is answered or the cause is gone
In ProgressReviewingAssigneeThe pull request is open and recorded (pull_request_url), and the ## Debrief is written
ReviewingCompletedLanding automation or personMerged 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
ReviewingBlockedLanding automationA post-merge run failed, was cancelled or timed out. When a person dismissed the review, also a failed check on the pull request
BlockedReviewingAssigneeA fix for a failed pull request check is pushed
BlockedCompletedLanding automation or personA re-run of the failed workflow succeeded, or a person closes the task once it is fixed
Any open statusCancelledPersonIt 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 blocks edge to what it waits on.
  • Only a person cancels a task, and the summary says why.