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

# Sofia investigations

> Read the findings from Sofia's scheduled investigations on the Sofia AI page, work through the full history, and act on each one.

Sofia runs scheduled investigations over the simulations and uploaded conversations in your workspace and records what it finds as **findings**: a titled, categorized summary with a short narrative and the evidence behind it.

Findings surface in two places. **Sofia AI** carries a short briefing of the findings that matter most right now, and the **Investigations** page holds the full history so you can see what Sofia detected, what your team changed, and whether an issue came back.

## Read the briefing on the Sofia AI page

Open **Sofia AI**. Once your workspace has at least one agent, the **Recent Investigations** section lists the top findings since the last briefing, ordered by priority. A line under the heading shows how far analysis has progressed, for example "Simulations analyzed through" and "Conversations analyzed through" a given time, so you know how current the findings are.

Each finding shows a category badge, a title, and a narrative explaining what Sofia saw. Select **Show evidence** to load the simulations or conversations that support it, and **Hide evidence** to collapse them again. Select **View all investigations** to open the full history.

| Category | What it means |
| - | - |
| **Failure pattern** | A repeated way the agent fails to complete the task. |
| **Policy & safety** | The agent did something it should not have. |
| **Unexpected behavior** | The agent behaved in a way the scenario did not call for. |
| **Configuration error** | Something in the agent, test set, or persona setup is wrong. |
| **Metric disagreement** | An evaluation result that needs a human look. |
| **Metric improvement** | A proposed change that would make a metric more precise. |
| **Test case improvement** | A proposed change or addition to your test coverage. |

## Work through the full history

Open **Investigations** in the sidebar, or select **View all investigations** on the Sofia AI page. The page opens with four summary tiles: **Active**, **Open**, **Resolved**, and **Regressions**.

Below the tiles, filter and sort the list:

* **Status**: any combination of **Open**, **Acknowledged**, **Resolved**, and **Dismissed**. The page starts with Open and Acknowledged selected.
* **Category**: one of the categories above, or all of them.
* **Regression**: **All findings** (the default) or **Regressions only**, to focus on findings that returned after being resolved.
* **Seen within**: **Last 24 hours**, **Last 7 days** (the default), **Last 30 days**, **Last 90 days**, or **All time**.
* **Sort by**: **Priority** (severity, whether it is still happening, and how often it repeats) or **Last seen**.

Each finding shows when it was first seen, when it was last seen, and how many times it has occurred. A **Regression** badge marks a finding that Sofia reopened because the issue returned after your team resolved it. Select **Show activity** to see the finding's history of status changes and notes, and resolved findings show the resolution your team recorded.

## Act on a finding

Every finding, on the Sofia AI page and on the Investigations page, carries the same set of actions.

**1. Acknowledge it**

Select **Acknowledge** to record that someone has seen the finding. The
button changes to **Acknowledged** and the finding stays active until you
resolve or dismiss it.

**2. Ask Sofia**

Select **Ask Sofia** to open a chat pre-filled with the finding. Sofia uses
the stored finding and its evidence to explain the impact, separate a real
issue from expected testing behavior, and recommend the next concrete
action. Ask follow-up questions or have Sofia propose the fix.

**3. Mark it resolved**

After you change something, select **Mark resolved**, describe what changed
(this note is required), and select **Record resolution**. Once a finding is
resolved, select **Validate fix** to open Sofia with the finding, its
evidence, and its resolution history. Sofia checks the connected agent
configuration and proposes a small targeted evaluation run for you to
confirm and verify that the fix holds. If the same issue shows up again
later, Sofia reopens the finding and marks it as a **Regression**.

**4. Dismiss or flag it**

Select **Dismiss** to remove a finding you do not intend to act on. If the
finding itself is wrong, select **Flag wrong**, optionally tell Sofia what
it got wrong, and select **Flag as wrong**. This feedback helps Sofia avoid
repeating the mistake. You can flag a finding after dismissing it. If you
need to bring a dismissed finding back into active work (or reverse a
mistaken **Flag wrong** dismissal), select **Reopen** to return it to
**Open** with its evidence and activity history intact.

> [!TIP]
>
> Select **Copy link** on any finding (in the **Sofia AI** briefing or on the
> **Investigations** page, including resolved findings) to copy a direct,
> workspace-scoped URL (`?finding_id=<id>`). Opening the link highlights that
> finding, scrolls to it, resets filters that would hide it (including Status,
> Category, Regression, and Seen within), and looks up the exact finding even
> if it falls outside the initial history window. If the linked finding does
> not exist in the workspace, the page shows a notice instead of an empty list.

## Scope

Findings belong to the workspace you have open. Switching workspaces switches the briefing on the Sofia AI page and the history on the Investigations page. Anyone in the workspace sees the same findings, and acknowledging, resolving, or dismissing one changes it for everyone.

> [!NOTE]
>
> Scheduled investigations are enabled per organization. If the Sofia AI page does not show
> a **Recent Investigations** section, or the Investigations page reports that
> investigations are not available for your organization, contact
> [support@coval.dev](mailto:support@coval.dev).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.