Task model frustrations

[lowellrex]

Goals

This ticket exists to collect frustrations we experience as developers with the Task model. The goal of this ticket is to discover common themes in our daily frustrations so that we can understand what they are and how we might best address them (better documentation, code/database changes, re-naming, improved tooling, perhaps even doing nothing at all).

Non-goals

This ticket will not be the place to propose solutions to any problems we surface during this frustration collection phase. If solutions become apparent during this phase, we will proposed them in separate Github tickets dedicated to the discussion of that particular solution.

What does the Task model do well?

While the goal of this ticket is to improve the Task model, it is important to acknowledge what the Task model does well so we do not end up throwing the baby out with the bath water.

• Tracking which parties have to take some action on an appeal
• Provide hierarchy of tasks that must happen in sequence
• Relationships are easy to understand in the database (via parent_id field)

What does the Task model do poorly?

I will update this section with themes that emerge from comments threaded on this ticket.

[lowellrex]

Difficult to describe which actions are available at a task at a glance

We are often asked by teams at the Board, newcomers to the team, and designers which actions are available for a task in a given state. In order to answer this question we must either find a task in this state and ask it directly (task.available_actions(user)) or climb through the code, being mindful of method inheritance and our extensive use of super() calls that varies amongst the task classes. If we are asked to determine the actions available for three different states of tasks, we must repeat this exercise three times.

We do not have a systematic way to determine the actions available on a task. We are incapable of enumerating all the possible actions available for all tasks in all states. There is an existing tech spec that describes one route to address this issue.

[lowellrex]

Hard to determine why a task's state changed

With the introduction of Task versions it is easier than ever to see what happened to a given task. However, I find it difficult to understand why that change happened by looking at the task tree, appeal state, or digging through the code. Tasks are updated in a ton of different ways, often without any addition to the instructions field. Additionally, the labyrinth of lifecycle callbacks we have on the Task model, and all the various ways we override these functions results in the investigation process taking a long time, often concluding with a thesis but little confidence that it is correct.

[lomky]

Differing Usages Across Teams / Code Pieces

Tasks in Queue, Hearings or Intake have slightly different behaviors & assumptions

• Intake tasks don't stem off of root task
• Org/Child Tasks or not
• when do we create anew off of Root Task vs create a holding parent task (i.e. HearingTask)

[lowellrex]

Expect task tree to reveal state of appeal

We rely on the state of the task tree to determine the status of AMA Appeals. These are really two distinct pieces of information (the status of the appeal, and the state of the appeal's task tree) but we use one to infer the other. This can result in the application (or developer's doing manual cleanup) changing the appeal's effective status by manipulating the task tree in an undocumented way.

In particular, I am regularly tripped up while debugging some issue in production with an appeal that has been cancelled in some way (or withdrawn) because we infer that status from the state of the task tree. I often try to figure out how a task tree ended up in the state that the task tree is in before realizing that the entire appeal may have been cancelled.

[hschallhorn]

Confusion between the many ways to create a task

Certain tasks rely on create_many_from_params or create_from_params to ensure they are in the correct state after creation, but developers that do not know this may simply use ActiveRecord#create

[lowellrex]

Difficult to learn

We have a lot of custom behaviour tied to each task class, increasing the volume of information needed to be learned before feeling comfortable with Tasks more generally. One aspiration of the initial generic Task effort was to create a framework for quickly and easily creating new task types for different stages of an appeal's lifetime at the Board. This has not borne out over the past 12+ months working with Tasks. In order to add new task types, add new actions to existing ones, or update behaviour, we must understand how Caseflow's tasks map to the business domain and how the current arrangement solves the business problem. As a result, we've ended up in a place where there is a lot of custom code in each task class definition. This custom code reduces the transferability of knowledge from one task class to another. Knowing how the QualityReviewTask branch operates does not tell us much about how DistributionTasks or ColocatedTasks work.