> ## Documentation Index
> Fetch the complete documentation index at: https://docs.causeloop.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Issues

> Understand the Issues list, issue detail view, the AI analysis pane, and the full issue lifecycle from ingestion to resolution.

An **issue** is any discrete failure event — an incident, a defect, a failed check — that arrives from a connected source or is created directly. Causeloop ingests issues, runs AI analysis on each one, groups related issues into [patterns](/product-guide/patterns), and tracks them through to resolution.

## The Issues list

Navigate to **Issues** in the left sidebar to open the issues list. The list is sorted by risk score (highest first) by default.

### Filtering and sorting

The top bar provides quick-filter tabs:

| Tab           | Description                                             |
| ------------- | ------------------------------------------------------- |
| **All**       | Every issue regardless of status                        |
| **In loop**   | Issues in `in_loop` status — the highest-priority queue |
| **New**       | Freshly ingested, not yet analyzed                      |
| **Analyzing** | AI analysis running                                     |
| **Resolved**  | Closed issues                                           |

For more precise filtering, use the full filter panel. You can filter by severity (`p1`–`p4`), status (one or more), source, assigned team, risk score range, pattern linkage, and date range. Valid sort fields are `risk_score`, `ingested_at`, `source_created_at`, `severity`, `status`, and `updated_at` (prefix with `-` for descending).

Filters can be saved as **Saved Views** for quick recall. Select **Save view** from the filter panel to name and share a view with your team.

### Bulk actions

Select multiple issues using the row checkboxes, then choose a bulk action:

* **Change status** — transition all selected issues to a new status
* **Assign** — set the assignee or team on all selected issues
* **Pin to pattern** — attach all selected issues to a pattern (creates an `include_issue` pin)
* **Export** — download selected issues as CSV

Bulk operations are processed via `POST /v1/issues/bulk`.

### Top-bar actions

* **Export CSV** — export the current filtered view
* **Ingest event** — manually create a new issue

## Issue detail

Click any row in the list to open the issue detail page. The URL is `/issues/{id}`.

### Header

The header shows:

* **Breadcrumb**: Issues / `{external_id}` (e.g. `JIRA-1042`)
* **Status pill** — the current lifecycle status (see below)
* **Severity chip** — `P1`–`P4`
* **Source chip** — the connected system the issue came from (e.g. PagerDuty, Jira, Linear)
* **Timestamps** — ingested at and analyzed at (UTC)

Three action buttons appear in the top bar: **Assign**, **Pin to pattern**, and **Re-analyze**.

### Agent analysis (left column)

The left column contains the AI verdict for this issue:

| Section                  | Content                                                   |
| ------------------------ | --------------------------------------------------------- |
| **The cause**            | One-sentence root cause summary                           |
| **Root cause detail**    | Longer explanation of why the failure occurred            |
| **Contributing factors** | Chips listing the conditions that enabled the failure     |
| **Why it recurs**        | Why previous incident closures did not prevent recurrence |
| **Confidence ring**      | Visual gauge (0–1) showing AI confidence in this analysis |

### Causal chain (left column)

Below the analysis card, the **Causal chain** SVG traces the contributing factors (left dots) through convergence threads to the single root-cause node (right ring). If the issue is resolved, the ring turns green and displays a checkmark.

### Context (right column)

The right rail surfaces key metadata:

| Field                | Description                                                            |
| -------------------- | ---------------------------------------------------------------------- |
| **Recurrence / 30d** | Probability of this issue recurring within 30 days                     |
| **Loop · 90d**       | How many times this pattern has looped in 90 days and the average MTTR |
| **Team**             | Assigned team label                                                    |
| **Assignee**         | Assigned user                                                          |
| **External**         | External ticket ID with a link to the source system                    |

### Similar issues (right column)

The **Similar issues** section lists up to three issues with high pattern-match similarity. Each row shows the external ID, a truncated title, and the similarity score (e.g. `.89`). Click any row to open that issue's detail page.

The similar issues data comes from `GET /v1/issues/{id}/similar`.

## Issue lifecycle

Issues move through a defined set of statuses. The table below shows which transitions are allowed:

| From            | Allowed transitions                                                            |
| --------------- | ------------------------------------------------------------------------------ |
| `new`           | `analyzing`, `in_loop`, `wont_fix`                                             |
| `analyzing`     | `analyzed`, `in_loop`, `wont_fix`                                              |
| `analyzed`      | `in_loop`, `pattern_found`, `mitigating`, `resolved`, `wont_fix`               |
| `in_loop`       | `analyzing`, `analyzed`, `pattern_found`, `mitigating`, `resolved`, `wont_fix` |
| `pattern_found` | `mitigating`, `in_loop`, `resolved`, `wont_fix`                                |
| `mitigating`    | `resolved`, `in_loop`, `wont_fix`                                              |
| `resolved`      | `in_loop` (if recurrence detected)                                             |
| `wont_fix`      | `in_loop` (if recurrence detected)                                             |

<Warning>
  You cannot skip statuses arbitrarily. Causeloop validates each transition and returns a `422 invalid_transition` error if the move is not permitted.
</Warning>

### Triggering re-analysis

Click **Re-analyze** in the top bar to run a fresh AI analysis pass on an issue. You can optionally choose a model tier: `fast`, `balanced`, or `deep`. The issue moves to `analyzing` immediately and the result is written back when complete.

### Linking to a pattern

Click **Pin to pattern** to associate this issue with an existing pattern. This creates an `include_issue` pin via `POST /v1/patterns/{id}/pins`, which the engine honors as a hard constraint on every subsequent run — pins outrank the majority-vote anchoring, so the link survives reruns. The issue status advances to `pattern_found` automatically. To remove the association, delete the pin with `DELETE /v1/patterns/pins/{pin_id}` (or create an `exclude_issue` pin to keep the issue out of that pattern going forward).

## iPad triage view

On tablet-sized screens (641–1024 px), the Issues screen shows a split layout: a scrollable queue on the left and a triage pane on the right. The queue shows only P1 in-loop issues sorted by priority. Selecting a row loads the triage pane, which displays:

* Severity and status pills
* Pattern association chip (if linked)
* Three KPI tiles: **Risk score**, **Recurrence / 7d**, **Loop · 90d**
* **Agent analysis** card with the confidence ring, cause summary, and contributing-factor chips

Action buttons in the triage pane sub-appbar are **Assign** and **Re-analyze**.

## API reference

The Issues API is documented at `/api-reference/overview`. Key endpoints:

| Endpoint                            | Description                                                                    |
| ----------------------------------- | ------------------------------------------------------------------------------ |
| `GET /v1/issues`                    | List issues with filters and pagination                                        |
| `POST /v1/issues`                   | Create an issue manually                                                       |
| `GET /v1/issues/{id}`               | Get full issue detail                                                          |
| `PATCH /v1/issues/{id}`             | Update status, assignee, or severity (pattern association is managed via pins) |
| `POST /v1/issues/{id}/analyze`      | Trigger re-analysis (extract → criticality → root-cause, chained)              |
| `GET /v1/issues/{id}/events`        | Ordered, machine-readable event log for this issue                             |
| `GET /v1/issues/{id}/root-cause`    | Get the issue's classified root cause                                          |
| `PUT /v1/issues/{id}/root-cause`    | Human override of the root-cause classification                                |
| `POST /v1/patterns/{id}/pins`       | Pin this issue to a pattern (`include_issue`, `exclude_issue`)                 |
| `DELETE /v1/patterns/pins/{pin_id}` | Remove a pin                                                                   |
| `GET /v1/issues/{id}/similar`       | Fetch similar issues                                                           |
| `GET /v1/issues/facets`             | Get filter facet counts                                                        |
| `POST /v1/issues/bulk`              | Bulk-update up to 200 issues                                                   |

## Related pages

<CardGroup cols={2}>
  <Card title="Patterns" icon="diagram-project" href="/product-guide/patterns">
    See how issues group into recurring patterns.
  </Card>

  <Card title="Recommendations" icon="lightbulb" href="/product-guide/recommendations">
    Act on the fix Causeloop recommends for a pattern.
  </Card>

  <Card title="Search & Activity" icon="magnifying-glass" href="/product-guide/search-activity">
    Find any issue instantly with global search.
  </Card>
</CardGroup>