Assistant Building

What are symptoms and solutions?

Symptoms and solutions are nodes that let you build flows that act like checklists.

For example, suppose you have a digital clock that can have a few different problems. If you were to write out a checklist for support agents to help users go through these problems and their fixes, it might look something like this:

1. Is the display on?

   1. If not, check that the clock is plugged in.

   2. If the display is still not on, confirm that the outlet it's plugged into is powered.

   3. If the display is still not on, the device needs to be repaired or replaced.

2. Is the display flashing "12:00"?

   1. If so, hold the "SET" button and press the "HOUR" and "MINUTE" buttons until the correct time is displayed.

3. Is the display flickering?

   1. If so, check that the plug is connected firmly.

   2. If the display is still flickering, the device needs to be repaired or replaced.

For each of the three numbered problems, you only need to consider its associated fixes if that particular problem is present. If it isn't, you skip them and move on to the next problem in the list.

By using symptoms and solutions, you can create this same behavior in a flow. Here's one way you might represent the above troubleshooting checklist:

First, the assistant will ask the user if they are having a problem with their clock. If they say yes, they are then presented with the symptoms. Just like a support agent going through the numbered problems in the written checklist, the assistant will go through the purple symptom nodes one at a time.

If the user indicates that a symptom is not present, the assistant won't bother with that symptom's orange solution nodes; it'll step back and move on to the next symptom. Once the user indicates that a symptom is present, then the assistant will move forward into that symptom's associated solutions - presenting them one at a time until the symptom is resolved, just like with the numbered fixes in the checklist.

For example, a user might be asked if their display is on. If it is, they don't need to be suggested to plug in the clock or confirm the outlet is powered. So they will then be asked whether the display is flashing "12:00". If they say it is, they will then be prompted to set the clock's time.

In short - when a symptom is rejected as not relevant or a solution is rejected as not fixing the problem, the assistant backtracks a step and moves on to the next symptom or solution. It only moves forward once a symptom is accepted as relevant.

Why use symptoms and solutions?

For checklist-style behavior, they make flows much easier to build, read, and maintain.

Here, for example, is how you could represent the above checklist using a more flowchart-like approach:

Instead of symptoms and solutions, this approach uses questions and solutions that don't have automatic backtracking. Because of this, all questions and solutions need to be manually connected to each other in the correct order for the flow to work. The connections between the nodes represent the order in which they will be shown to the user, rather than the logical relationship between the questions and solutions.

This can make the flow harder to read. In the symptom-based version, it's clear that "Plug in the clock", "Confirm outlet is powered", and "Repair or replace" are all potential solutions to the problem of the display not being on because they are all connected directly to that symptom. In this question-based version, to find out which problem "Confirm outlet is powered" is meant to solve, you have to trace the connections back through the "Plug in the clock" solution before you get to the "Is the display on?" question.

For the same reason, the flow can be harder to maintain. If you find a new solution to add in between plugging in the clock and confirming the outlet was powered, in this question-based version you'd first need to disconnect those two solutions from each other and then connect them both to your new solution in the right way. The same goes for adding new questions if there are new problems users might encounter.

With symptoms and solutions, each solution is connected directly to the symptom it is meant for and you can connect new solutions directly to that symptom as well. Similarly, you can easily add new symptoms without needing to reconnect existing symptoms.

This digital clock example is a very simple flow where each problem leads directly to one or more solutions. In real troubleshooting scenarios for complex products, flows can become much larger with nested questions or symptoms and the complexity can ramp up fast. In these cases, the increased readability and expressiveness of symptoms and solutions can drastically cut down on time to build or update a flow as well as reduce the opportunity for errors.

What is a symptom?

A symptom is a node representing an observable problem a user might encounter with a product.

Symptoms are presented to the user as questions with two answers. One answer reflects the "working" state, indicating that this problem is not present, and one reflects the "faulty" state, indicating that this problem is present.

For example, in the above symptom the assistant will ask the user, "Is the display on?" If they answer "Yes", that means the display is working and this symptom is not relevant. The assistant will then backtrack and go to the next symptom. (If the assistant runs out of symptoms, it will go to the Out of solutions" jump target

If the user instead answers "No", that means the display is faulty and this symptom is relevant. The assistant will then move forward into the connected solutions.

It's generally best to phrase these as yes or no questions, but this is not required. For example, you may have a product where an indicator light is normally green but is red if there is a problem. In this case, you may ask "What color is the indicator light?" with "Green" being the "working" answer and "Red" being the "faulty" answer.

Note that symptoms are named as positive statements that reflect the faulty state rather than as questions - in the above example, the question asked to the user is "Is the display on?" but the name of the symptom is "Display not on." This is because in some circumstances, users are prompted to select from a list of symptoms; in these cases the positive statement is more clear.

What is a solution?

A solution is a node representing instructions for a potential fix to a user's problem.

Solutions are presented to the user as instructions followed by a prompt for the user to indicate whether the solution solved the problem.

For example, in the above solution the assistant will tell the user, "Check that the clock is plugged in." If they indicate that this solved the problem, the assistant moves to its "Success" jump target.

If the user instead indicates that this solution did not resolve the problem, the assistant will backtrack and go to the next solution. (If the assistant runs out of solutions, it will go to the "Out of solutions" jump target.