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

# Vortex Mind: AI root-cause diagnostics for ecommerce

> Vortex Mind explains why a metric moved by joining signals across all your connected sources, then creates ranked Actions for you to approve and apply.

Vortex Mind is the diagnostic engine inside Vortex IQ AI OS. While Nerve Centre tracks your metrics and detects when something moves, Vortex Mind explains **why** it moved. It walks your connected sources - Shopify, Stripe, Google Ads, Klaviyo, Datadog, and more - joins the evidence into structured findings, and creates Actions ranked by revenue impact that you can approve and apply. It is the difference between a dashboard that shows you a number and an AI Operating System that tells you what to do about it.

## Vortex Mind vs Nerve Centre

These two modules are complementary but distinct:

| Module           | Question answered                                                                       |
| ---------------- | --------------------------------------------------------------------------------------- |
| **Nerve Centre** | What moved? Tracks KPIs and fires when a metric crosses a threshold.                    |
| **Vortex Mind**  | Why did it move? Walks the connector graph, gathers evidence, and produces a diagnosis. |

When Nerve Centre flags a refund-rate spike on Shopify, Vortex Mind takes over: it checks whether checkout latency rose on Datadog at the same moment, whether the spiked SKU is also out of stock on Amazon while ad spend is still active on Google Ads, and whether a Stripe gateway-decline pattern is hiding inside the order data. The answers become a finding, evidence, and an Action.

## The diagnostic report types

Vortex Mind has seven diagnostic report types. Each report is a named recipe - a deterministic set of graph queries, evidence-gathering steps, and recommendation formulas - that runs against the connector graph and produces structured findings. The seven types cover payment performance, decline recovery, checkout conversion, daily revenue, customer recovery, Google Ads attribution, and paid traffic waste.

## The diagnostic flow

Every Vortex Mind run - whether triggered by a scheduled briefing, a Nerve Centre anomaly, or a question you ask via Ask Viq - follows the same five-stage reasoning loop:

<Steps>
  <Step title="Signal detected">
    A trigger arrives: a Nerve Centre threshold breach, a scheduled report run, an anomaly score, or a conversational request through Ask Viq. The trigger object carries a metric ID, an anchor node in the connector graph, and a time period.
  </Step>

  <Step title="Graph walk">
    Vortex Mind loads all connector graphs - one JSON file per connected source in `auth/integration_graphs/` - and runs a breadth-first search from the anchor node outward. Most reports walk two hops; cross-platform reports walk three or four to bridge the source of truth and the attribution surface. The result is a candidate set of every related node within the hop budget.
  </Step>

  <Step title="Evidence gathered">
    Each candidate node is checked for supporting evidence: metric snapshots with before-and-after values, log entries from connected observability sources, other findings already in the graph, time-series patterns (step, spike, drift, regression, seasonal), recent deploy events from Vortex Apps, and schedule changes in Klaviyo or Google Ads. Every piece of evidence is timestamped and ranked by recency and relevance.
  </Step>

  <Step title="Finding produced">
    The evidence bundle is compiled into a structured finding with a stable `finding_id`, a severity tier, a confidence score from 0 to 1, a plain-language narrative, pointers to the supporting evidence nodes, and an optional pointer to a Recovery as a Service (RaaS) catalogue entry for the fix.
  </Step>

  <Step title="Action proposed and approved">
    When a finding's severity is `high` or `critical`, or when it matches a RaaS recipe, Vortex Mind emits a Kanban card to your Actions board. The card carries a title, an owner role, an effort tier, and an expected revenue lift. Nothing changes on your store until you approve the Action.
  </Step>
</Steps>

<Note>
  Each stage writes its output back to the connector graph so the next run starts from a richer baseline. The second day of Vortex Mind is materially better than the first because the graph compounds.
</Note>

## How findings are generated

A finding is a structured statement of cause. Every finding has a fixed shape:

| Field                      | What it carries                                                                                                                       |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `finding_id`               | Stable identifier scoped to the recipe and integration, e.g. `finding:PAY-AUTH-001`. Deduped across runs so you never see duplicates. |
| `severity`                 | One of `critical`, `high`, `medium`, `low`, or `info`.                                                                                |
| `confidence`               | A score from 0 to 1 computed deterministically from the evidence bundle.                                                              |
| `narrative`                | A plain-language one or two sentence explanation written for you to read.                                                             |
| `evidence_node_ids`        | Pointers to the graph nodes that support the finding - click through to verify any claim.                                             |
| `suggested_action_node_id` | Optional pointer into the RaaS catalogue when a fix recipe exists.                                                                    |

Findings are written as nodes into the connector graph with the prefix `finding:*`. Re-running the same recipe against the same window updates the existing node rather than creating a duplicate, so downstream consumers - the Kanban board, briefings, and integrations - never see a duplicate alert.

## The severity model

Every finding is assigned exactly one severity tier. Severity is recipe-driven - what counts as `critical` for Daily Revenue Leakage differs from what counts as `critical` for the Quarterly Business Review:

<AccordionGroup>
  <Accordion title="Critical - immediate revenue impact">
    Triggered by revenue impact greater than 5 percent of trailing 30-day revenue, a complete checkout failure, or a payment vendor outage. Pages your on-call contact, auto-routes the Kanban card to the top of the queue, and displays a red severity badge.
  </Accordion>

  <Accordion title="High - material revenue impact">
    Triggered by revenue impact of 1 to 5 percent of trailing 30-day revenue, or a known-fixable issue with a significant sized lift. Creates a Kanban card in Pending Review with a priority flag and surfaces in your next briefing.
  </Accordion>

  <Accordion title="Medium - worth reviewing">
    A drift, a regression, or a moderately-sized opportunity. Creates a Kanban card without a priority flag and surfaces in the next weekly report.
  </Accordion>

  <Accordion title="Low - early warning">
    A small drift or an early-warning signal. No Kanban card unless you have manually subscribed this finding type. Appears in the report HTML and the connector graph.
  </Accordion>

  <Accordion title="Info - pure context">
    Used for verification findings, baseline statements, and confirming a fix worked. Never creates a Kanban card. Appears inline in reports.
  </Accordion>
</AccordionGroup>

You can manually escalate or de-escalate a finding's severity at any time, and that override is preserved across future re-emissions.

## The seven report types

<CardGroup cols={2}>
  <Card title="Payment Performance Intelligence" icon="credit-card">
    Auth rates, decline reason codes, payment method mix, and BIN-level patterns. The deepest payment-side diagnostic.
  </Card>

  <Card title="Decline Recovery Intelligence" icon="arrow-up-right">
    Sizes the recoverable revenue from declined and incomplete orders - the "Size of the Prize" framing.
  </Card>

  <Card title="Checkout Conversion Failure" icon="funnel">
    Stage-level checkout funnel breakage with dollar value behind each drop-off step and device-level breakdown.
  </Card>

  <Card title="Daily Revenue Leakage" icon="calendar">
    The 90-second morning briefing: yesterday's failures and the single highest-leverage move for today.
  </Card>

  <Card title="Customer Recovery Opportunity" icon="users">
    A ranked, contactable list of customers to recover now, with channel and message template pre-suggested.
  </Card>

  <Card title="Google Ads Revenue Intelligence" icon="chart-line">
    Ads spend to revenue attribution with waste callouts, cross-platform insights, and a 90-day action roadmap.
  </Card>

  <Card title="Paid Traffic Waste" icon="ban">
    Paid-channel waste identification with a Pause Now list and a Fix Tracking list for broken UTMs.
  </Card>
</CardGroup>

## How Vortex Mind connects to other modules

Vortex Mind sits at the centre of the Vortex IQ AI OS:

* It reads from every connector wired into **Nerve Centre**.
* It produces findings that route to **Actions** for triage and resolution on the Kanban board.
* It archives every report run into **Vortex Memory** for retroactive analysis and the historical lift database.
* It contributes structured citations that **Ask Viq** draws from when you ask "why did revenue drop last Tuesday?".

<Tip>
  Vortex Mind is a read-only reasoning layer. It reads from your connectors and emits Actions to the Kanban board for your approval. Any change to your live store happens through Actions or a Vortex Apps integration - both of which require your explicit approval before anything executes.
</Tip>