> ## 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.
* **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.

<Steps>
  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Mark it resolved">
    After you change something, select **Mark resolved**, describe what changed
    (this note is required), and select **Record resolution**. If the same
    issue shows up again later, Sofia reopens the finding and marks it as a
    **Regression**.
  </Step>

  <Step title="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.
  </Step>
</Steps>

<Tip>
  Each finding has a shareable link. Opening the Investigations page with
  `?finding_id=<id>` in the URL highlights that finding, scrolls to it, and
  widens the filters so it is visible whatever its status or age. If the linked
  finding is outside the loaded history, the page says so instead of showing
  an empty list.
</Tip>

## 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).
</Note>