# How the analysis works

> What triggers Sypnia's analysis of a problem, what it reads, the steps it takes, what it writes, what it never does, and how it shows that it does not know.

Applies to: the Sypnia engine (open source, self-hosted) and Sypnia Cloud (paid service). Status: at launch.  
Source: https://docs.sypnia.com/agent/how-the-analysis-works/

For agents: The pipeline of Sypnia's analysis: triggers (new, grows, comes back, on request), inputs (failure, stack with source lines, breadcrumbs, trace, release changes, impact), the five steps, the output fields and confidence rules, failure modes (not_enough_evidence, failed, limit_reached, off), and the weekly suggestions.

**\[Engine]** **\[Cloud]** This page is for anyone who wants to know what stands behind the sentence «3 people tried to pay today and could not». It is the same on Sypnia Cloud and on a self-hosted engine with a model configured. Without a model the agent is off and everything else in Sypnia still works.

> **In plain words**
>
> When something breaks, Sypnia gathers the facts by itself: where the code failed, what the person did, which request failed, what changed in the last release, how many people it hit. Then it asks a language model one question: given these facts, what happened and why? It keeps the answer only if the answer points at those facts. If the facts are not enough, it says so instead of guessing.

## When it runs

| Trigger                  | When exactly                                                                                                                                                              |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **A problem is new**     | Right after the engine creates the problem, within 2 minutes of the first failure                                                                                         |
| **A problem grows**      | When it reaches twice the people it had at its last analysis, and when it is first seen in a newer release                                                                |
| **A problem comes back** | When a resolved problem happens again                                                                                                                                     |
| **You ask**              | The «Analyse again» button, or [`POST /v1/problems/{problem}/analyze`](https://docs.sypnia.com/api/problems). Useful after you upload source maps or register the release |

It does not run for ignored problems, for projects that switched the agent off, or beyond the [limits](https://docs.sypnia.com/agent/limits): at most 3 times a day for one problem.

## What it reads

Everything the agent reads is collected by the engine with fixed rules, before any model is involved. It is exactly what [`GET /v1/problems/{problem}/context`](https://docs.sypnia.com/api/problems) returns.

| Input                        | What it is                                                                                                                | Where it comes from                                              |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
| The grouped failure          | The error's name and message, or the call that failed and how                                                             | The events of the problem                                        |
| The stack, with source lines | The frames in your own files and a few lines of code around each                                                          | The error's stack, translated with the release's source maps     |
| Breadcrumbs                  | What the person did before: pages opened, things clicked by their label, calls made. Up to 30                             | The session of one occurrence                                    |
| The trace                    | The failing request followed from the browser to the API to the calls behind it                                           | The trace of that occurrence                                     |
| The release and what changed | The version the failure was first seen in, when it went live, its commits, changed files and, if you send them, the diffs | [Releases](https://docs.sypnia.com/api/releases-and-source-maps) |
| The impact                   | How many people, sessions and occurrences; how many tried again; when the same page last worked                           | The engine's counts                                              |

Any of these can be missing. No source maps means a minified stack; no registered release means no «what changed». The agent works with what there is and its confidence drops accordingly.

## The steps

### 1. Collect

The engine picks one occurrence to study: the latest one that has both a trace and a session. It builds the context above. No model yet.

### 2. Redact

The engine removes what must not leave, by rule: people become «person 1», «person 2»; ids, names and e-mails are dropped; labels of list rows and of free text are replaced by their kind («a row»); values that look like tokens or keys are cut out of messages and URLs. With `SYPNIA_AI_SEND_SOURCE=false` the source lines and diffs are dropped too. The exact list is on [Models and what is sent](https://docs.sypnia.com/agent/models-and-what-is-sent).

### 3. Ask

One call to the model, with fixed instructions and the redacted context as JSON. The model must answer in a fixed JSON shape, and every claim about the cause must name the piece of context it rests on. The agent has no tools and makes no other request: it cannot browse, run code or read anything it was not given.

### 4. Check

The engine checks the answer against the context, by rule:

- The place it blames must be a frame of the stack or a file the release changed.
- Each piece of evidence must point at something that exists in the context.
- Numbers are not taken from the model. «3 people», «today», «18:40» are filled in by the engine from its own counts.

An answer that fails is asked for once more. If it fails again, the cause is dropped and the analysis becomes `not_enough_evidence`.

### 5. Write

The engine stores the analysis on the problem, builds [the prompt](https://docs.sypnia.com/agent/the-prompt) from it with a fixed template, gives the problem its readable slug, and sends the `problem.analyzed` webhook.

## What it writes

The `analysis` of a problem, in the API, the MCP server, the app and the Console:

| Field            | What it is                                                | Example                                                                                                             |
| ---------------- | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| `sentence`       | What happened, in one or two plain sentences              | «3 people tried to pay today and could not. The Pay button does nothing since yesterday's change.»                  |
| `who`            | Who it hit                                                | «3 people. Two of them tried again and gave up.»                                                                    |
| `doing`          | What they were trying to do                               | «Paying for an order, at the last step of checkout.»                                                                |
| `since`          | Since when, and whether it worked before                  | «Yesterday's change, deployed at 18:40. It worked before.»                                                          |
| `cause.text`     | The likely cause                                          | «Release 4f2a91c renamed the cart's total from cart.total to cart.totalCents. The checkout still reads cart.total…» |
| `cause.evidence` | One to six facts, each pointing at something you can open | `release_change` `4f2a91c:src/cart/cart.ts`; `stack_frame` `src/checkout/checkout.tsx:142`                          |
| `what_to_do`     | The change to make                                        | «Read cart.totalCents in confirmPayment(), and show the customer a message when a payment is rejected.»             |
| `confidence`     | How well the evidence supports the cause                  | `high`                                                                                                              |
| The prompt       | The same, as a brief for a coding agent                   | See [The prompt](https://docs.sypnia.com/agent/the-prompt)                                                          |

### Confidence

Confidence is set by rule from the evidence, not by how sure the model sounds.

| Level    | Rule                                                                                                                  |
| -------- | --------------------------------------------------------------------------------------------------------------------- |
| `high`   | At least two kinds of evidence agree, and one of them is a change in the release that touches the code where it fails |
| `medium` | The cause is supported by the stack or the trace alone, with source lines                                             |
| `low`    | The cause fits the facts and nothing confirms it: a minified stack, or no release information                         |

On Sypnia Cloud a pull request is only offered for `high` and `medium`.

## What it never does

- It never sees replay recordings, page snapshots or screenshots. It reads events as text.
- It never reads what a person typed. That is never collected.
- It never receives anything inside a masked element, nor names, e-mails or ids of people.
- It never reads your repository on a self-hosted engine. It sees only the source lines in your source maps and the diffs you chose to send. On Sypnia Cloud the repository is read only to write a pull request you asked for.
- It never changes your code, never merges, never resolves or ignores a problem.
- It never calls a model before you configure one, on a self-hosted engine.

## When it does not know

A wrong cause, stated with confidence, costs more than no cause. So every way the analysis can fall short has its own status, shown as it is.

| `analysis.status`     | What happened                                                        | What you see                                                                                                                                                           |
| --------------------- | -------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ready`               | A cause was found and passed the checks                              | The full analysis                                                                                                                                                      |
| `not_enough_evidence` | The agent could describe what happened and could not support a cause | The sentence, who, doing, since. In place of the cause: «Not enough evidence to name a cause», with what is missing (for example «no source maps for release 4f2a91c») |
| `pending`             | It is running                                                        | The technical title, and «analysing». Usually under a minute                                                                                                           |
| `failed`              | The model call failed or timed out three times                       | The technical title, and «the analysis failed; it will be tried again when the problem grows»                                                                          |
| `limit_reached`       | The project used its analyses for today                              | The technical title, and when the count resets                                                                                                                         |
| `off`                 | No model is configured, or the project switched the agent off        | The technical title. Nothing was sent anywhere                                                                                                                         |

In every one of these the problem itself is complete: counts, sessions, replays, the trace and the stack are there, and the prompt still carries the evidence.

## Weekly suggestions

Once a week, on Monday at 07:00 UTC, the agent looks at the week that ended and proposes improvements to performance and to how the app is used. See [`GET /v1/suggestions`](https://docs.sypnia.com/api/performance).

It works in two parts. First, fixed rules over the numbers, with no model: a page whose INP at the 75th percentile is above 500 ms, more than 3 rage clicks per 100 views, an API route above 2 % of failures, a form field people keep failing. These run on every engine. Second, one model call per page that has findings, to say in plain words what to change. That part needs a model and sends only counts, routes, selectors and stable labels: never people, sessions or ids.

## Turn it off

| Where                       | How                                                                                                               |
| --------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| One project                 | Set `settings.agent.enabled` to `false`: `PATCH /v1/projects/{project_ref}`, or the project's settings in the app |
| A whole self-hosted engine  | Set `SYPNIA_AI_PROVIDER=none`, which is the default                                                               |
| Only the weekly model calls | `SYPNIA_AI_WEEKLY_SUGGESTIONS=false`                                                                              |

With the agent off, problems keep their technical title, alerts carry that title, and nothing is sent to any model provider.
