Skip to content

Root-cause agent

The root-cause agent investigates a failure and proposes where the bug is. You point it at a failure signature; it works through the failing log, the design and the testbench, and returns a hypothesis: the file and line it suspects, the commit that likely introduced the bug and its author, a confidence level, a short explanation and the evidence it relied on. A person reviews the hypothesis and confirms it; the agent never changes a signature's triage status by itself. This page explains when you can use the agent, what it costs, and how its results flow back into triage.

What you can run it on

Today the agent works on scenarios: a built-in library of designs with known bugs (see Scenarios). You can run it two ways:

  • From a signature, with Run root-cause, when the signature is mapped to a scenario.
  • Directly on scenarios, with New run on the Runs page. See Runs and hypotheses.

Signatures and scenario mappings

Run root-cause is enabled only for a signature that is mapped to a scenario. A signature gets a mapping when:

  • its failures were pasted on the Ingest regression page with a Scenario hint (optional — enables one-click root-cause); the signature takes the scenario most of its pasted failures named, if it had none yet; or
  • a mapped signature is merged into it and it had no mapping of its own.

Signatures from your own regressions (sent with the dvforge CLI or from CI) have no mapping. On those, Run root-cause is disabled, with a note under it saying it needs a scenario mapping. Running the agent on your own design and testbench isn't available yet.

Note

The agent's state is separate from triage. A signature can be Investigating in triage while the agent works on it, and finishing a run doesn't move it to Root-caused unless someone confirms it or a rule does (see below).

Who can run it

Starting a run, from a signature or from New run, needs the member role or higher. Viewers can read runs and hypotheses. See Permissions.

Time and cost

The app shows estimates before you start:

  • Each scenario on the Scenarios and New run pages shows its expected duration and cost (roughly 90–120 seconds and $0.45–$0.55 for the built-in scenarios).
  • New run offers two models: Sonnet 4.6 ("Default · ~$0.50/run") and Opus 4.7 ("Advanced · ~$2/run"). Run root-cause on a signature always uses the default.

Each run's actual cost and duration appear on the Runs list and the run's page once it finishes. The Dashboard totals spend for the month.

Start a run from a signature

  1. Open the signature.
  2. Select Run root-cause. The button shows Launching…, then DV Forge opens the new run's page, where you can follow the agent live.

The signature now shows the agent running badge, on its page and in the Signatures list. See Runs and hypotheses for what the run page shows.

Confirm the root cause

When a run started from a signature finishes, DV Forge records the result on the signature:

  • The agent badge changes to agent done (or agent failed).
  • The assignee, everyone watching the signature, and the person who started the run get an in-app notification: "Root-cause hypothesis ready: title" ("Review it and confirm the root cause."), or "Root-cause run failed: title". See Notifications.
  • The activity timeline records "Root-cause hypothesis ready — awaiting confirmation" (or "Root-cause run failed"), with a link to the run.

While the hypothesis waits for a decision, the signature's triage panel shows Root-cause hypothesis ready with Review the run → and, for triagers, Confirm root cause:

  1. Select Review the run → and read the hypothesis.
  2. If you agree, go back and select Confirm root cause. The signature moves to Root-caused.

If you disagree, leave the status as it is, or set it yourself; see Working a signature. The banner shows only while the signature is open and not already Root-caused.

Automate it with a rule

A project that trusts the agent's hypotheses can skip the manual step. Create a triage rule with the trigger A root-cause run finishes with a hypothesis and the action Set status → Root-caused. You can add other actions too, such as Notify or Add label.

Rules can also start the agent: the Run the root-cause agent action runs it on matching signatures. It's limited to 10 runs per rule in any 24 hours, and it's skipped for a signature that already has a run in progress or has no scenario mapping.