# Issue states and recovery

## Issue status and recovery

An issue is a report about a problem with published documentation, such as incorrect information,
outdated content, or a broken link. Atloria turns the report into a ticket that can be assigned,
tracked, and managed from the Issues dashboard.

The product-defined status choices include `Open`, `In Progress`, `Resolved`, and `Closed`. It also
provides `Waiting on customer` and `Paused` for work that remains at the In Progress point
in the journey.

```mermaid
stateDiagram-v2
    Open --> InProgress: Start Working
    InProgress --> Resolved: Mark as Resolved
    Resolved --> Closed: Close as Fixed
    Closed --> Open: Reopen Issue
```

| If you need to… | Go to |
|---|---|
| Find the Issues destination or choose a view | [Issues overview](doc:issues-overview) |
| Open and work with one issue | [Work with an issue](doc:work-with-an-issue) |
| Understand the controls and status flow on this page | [Understand the issue screen](#understand-the-issue-screen) |
| Change, close, or reopen an issue | [Change status and recover an issue](#change-status-and-recover-an-issue) |
| Filter activity, add a comment, or use a board | [Handle comments, boards, and status branches](#handle-comments-boards-and-status-branches) |
| Diagnose an update or empty-state message | [When an update does not work](#when-an-update-does-not-work) |
| Set up or maintain an issue board | [Manage issue boards](doc:manage-issue-boards) |

## Before you start

Issues are project-scoped reports. Select the project whose issues you need to review before you
open the Issues destination.

| Have this ready | Why it matters |
|---|---|
| The correct project | The dashboard, issue list, and boards use one project context. |
| An existing issue to review | The recovery controls operate on an issue record reached from the list. |
| The status, priority, or assignee change you need to make | Each corresponding control updates the record when its value changes. |
| The reason for closing an issue, if you are closing it | The close choices record whether the issue was fixed, duplicated, not reproducible, or will not be fixed. |

There is no separate save control for **Status**, **Priority**, or **Assignee**. Changing one of
these controls invokes its update action immediately.

With these items ready, open the Issues destination and find the issue you need to review.

## Find and open an issue

The Issues destination is the project-scoped entry point for reviewing reported issues. The full
list is the place to select an existing issue before you use its recovery controls.

**Prerequisites**

- You have selected the project that owns the issue.
- You know enough about the report to recognise it in the issue list.

**Steps**

1. Open the **Issues** destination.
2. Select **All issues** in the overview header.
3. Select the issue you need to review from the list.

**Result:** The selected issue record is on screen, with its status and recovery controls available.

## Understand the issue screen

The issue record brings the report, its current state, its history, and its recovery actions into one
working surface. The overview screen provides the statistics period and navigation to the list and
boards.

The main controls on the overview are:

| If you need to… | Select |
|---|---|
| Change the statistics period to seven days | **7d** |
| Change the statistics period to 30 days | **30d** |
| Change the statistics period to 90 days | **90d** |
| Open the complete issue list | **All issues** |
| Open issues arranged on boards | **Boards** |
| Reload the statistics and issue data | **Refresh** |
| Open the full issue list from recent reports | **View all** |

On the issue record, the fields and controls are arranged as follows:

| Area | What you use there |
|---|---|
| Issue identity | **What the reader said**, the report description, reporter, reported date, and page. |
| Status and management | **Status**, **Priority**, and **Assignee**. |
| Status journey | The current position across `Open`, `In Progress`, `Resolved`, and `Closed`. |
| Activity Timeline | **All**, **Comments**, or **Updates**. |
| Comment composer | `Reply to the reporter…` or `Jot an internal note…`, with **Public reply** or **Internal** visibility. |
| Close Issue | **Fixed**, **Duplicate**, **Won't Fix**, and **Not Reproducible**. |
| Supporting context | **Environment**, **On Boards**, and **Related Issues** when their conditions are met. |

The product-defined **Priority** choices are `Critical`, `High`, `Medium`, and `Low`.

`Waiting on customer` and `Paused` appear at the In Progress point in the status journey, while
keeping their own labels. The **Close Issue** area appears for every status except `Closed`.

![Identify the time-range and navigation controls on the Issues overview.](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/c1ca7247ae7037be0ec1289fa888bca0.png)

Use **Status** to change the status, or choose a named option in **Close Issue** to close the issue.

## Change status and recover an issue

Use the status journey when an issue is moving through normal recovery, and use a close reason when
the issue has reached a final outcome.

**Prerequisites**

- You have opened the issue record.
- You know the next status or the reason the issue is being closed.

**Steps**

1. Read the current position in **Status Journey**.
2. Select the action that matches the current status:

   | Current status | Select | Outcome |
   |---|---|---|
   | `Open` | **Start Working** | Moves the issue to `In Progress`. |
   | `In Progress` | **Mark as Resolved** | Moves the issue to `Resolved`. |
   | `Resolved` | **Close as Fixed** | Closes the issue with the **Fixed** reason. |
   | `Closed` | **Reopen Issue** | Moves the issue back to `Open`. |

3. Select **Status** to choose a different status, or select **Fixed**, **Duplicate**, **Won't Fix**,
   or **Not Reproducible** in **Close Issue**.

4. Read the status or close result on the record. A status change displays `Status updated`, a priority
   change displays `Priority updated`, and an assignee change displays `Assignee updated`. A failed
   update raises `Update failed`. A successful close raises `Issue closed`; a failed close raises
   `Close failed`.

**Result:** The issue shows the selected recovery state or close reason, and the corresponding result
message appears.

When the issue needs supporting coordination rather than a status change, continue with the timeline,
comment, board, or assignment controls.

## Handle comments, boards, and status branches

Comments, board placement, and activity filters support recovery work without replacing the issue's
status. Use them when the next action depends on a customer reply, internal coordination, or a record
of what changed.

**Prerequisites**

- You have opened the issue record.
- You know whether the comment is for the reporter or for the team.

**Steps**

1. When work is waiting for a response or paused internally, read **Status Journey** and use the
   **Status** choice that matches `Waiting on customer` or `Paused`.
2. In **Activity Timeline**, select one filter:

   | If you need to see… | Select |
   |---|---|
   | Comments and status activity together | **All** |
   | Comments only | **Comments** |
   | Status and assignment changes | **Updates** |

3. Select **Reply** to move to the comment composer.
4. Choose the visibility that matches the audience:

   | If the note is for… | Select |
   |---|---|
   | The reporter | **Public reply** |
   | The team only | **Internal** |

5. Enter the comment in `Reply to the reporter…` or `Jot an internal note…`.
6. Select **Send reply** for a public reply or **Add note** for an internal note. A successful
   comment raises `Comment added`; a failed comment raises `Failed to add comment`.
7. Select **Add to Board** when the issue also needs board coordination.
8. In the board picker, enter a board name in **Search boards...**, then select the matching board.
9. To assign the issue to yourself, select **Assign to me**. If you are already assigned, select
   **Unassign me** instead.

**Result:** The timeline shows the selected activity view, the comment uses the selected visibility,
and the issue is available on the selected board or assigned according to your choice.

## When an update does not work

Use the message text on screen to identify which recovery action needs attention. The issue record also
uses empty-state messages when the selected timeline or board list has no items.

| What appears | What to do |
|---|---|
| `Update failed` | Check the current status, then retry the status, priority, or assignee change. |
| `Close failed` | Confirm that the issue is not already `Closed`, then retry the close choice. |
| `Failed to add comment` | Check the comment text and its visibility, then retry the comment. |
| `Added <number> issue(s) to "<board name>"` | The issue was added to the displayed board name and issue count. |
| ``API error message, or `Couldn't add to board` `` | Check the board search and try the board action again. |
| `Removed from "<board name>"` | The issue was removed from the displayed board name. |
| ``API error message, or `Couldn't remove` `` | Check the board entry, then retry removing it. |
| `No activity yet` | Select **All** and use the status or comment controls to begin the issue history. |
| `No comments yet` | Select **All** or add a comment when you have the appropriate text. |
| `No updates yet` | Select **All** or change the issue status or assignment. |
| `No boards match` | Change the text in **Search boards...**. |
| `No boards yet` | Use the board-management path to create or maintain a board. |

The **Environment**, **On Boards**, **Related Issues**, and **Closed as** areas depend on the issue's
current information. If the relevant information is not present, continue with the status and recovery
controls that are on screen.

If an update still needs attention after these checks, continue with the next support path.

## What happens next

After a recovery action, the issue remains part of the Issues workflow: it can be reviewed in the list,
worked from its record, or coordinated through a board. A public tracking page lets reporters see the
issue status, public comments, and timeline without signing in.

| If you need to… | Continue with |
|---|---|
| Review the issue list and its views | [Issues overview](doc:issues-overview) |
| Continue working on the record | [Work with an issue](doc:work-with-an-issue) |
| Create or maintain the board used for coordination | [Manage issue boards](doc:manage-issue-boards) |
| Resolve a broader application problem | [Common issues and solutions](doc:common-issues-and-solutions) |
| Get help with a problem that remains | [Getting help](doc:getting-help) |