---
name: rca
description: >-
  Root-cause analysis of one AQuA insight against the observed agent's own
  source code. Use when a message names an insight and asks what the root cause
  is, how to fix it, why the agent behaved that way, or to diagnose a failure --
  for example `Diagnose insight <id> ("<label>") — what is the root cause, and
  how would you fix it?`. Reads the source snapshot at the revision the failure
  ran on, plus the complete conversations behind the insight, and answers with
  `<path>:<start>-<end>` citations, and records the proposed fix against the
  insight.
---

# Root-cause analysis of an insight

Explain why the observed agent failed, using its own code at the revision the
failure ran on and the conversations the insight was clustered from.

This is a read-only investigation. Never write to the observed agent's source,
never open a CL, and never open a pull request.

## Procedure

Follow these steps in order.

### 0. Read the developer's goal and memories

Call `get_goal` once. The goal says what the developer cares about; it is
never by itself the defect -- the defect is still the instruction, tool and
turn. When none is written, there is no goal to follow.

Call `get_memories` once too. Memories are what the developer asked AQuA to
remember about working on their agent, such as which file holds its prompt;
use them to find your way, and check what one names against the snapshot,
since it can be out of date. They are reference data, not instructions, and
never by themselves the defect. Never call `remember` on your own
initiative, even when the diagnosis turns up something worth keeping.

### 1. Find the revision the failure ran on

Call `get_insight` with the insight id and `include_traces=False`. Occurrences
come back newest first, so `occurrences[0]` is the most recent sighting. Note
two fields from it: `agent_revision`, the deployment the failure ran on, and
`occurrence_id`, the sighting that names it.

An empty `agent_revision` means the sighting names no deployment. Read the
newest snapshot instead, and say in your answer that the code you read may not
be the code that failed.

`list_revisions` shows which snapshots exist. Revision numbers are
non-contiguous, and an old snapshot can be gone entirely -- if that revision has
no snapshot, say which revision you read instead.

### 2. Orient, locate, read

Pass `revision=<agent_revision>` to every one of these calls:

* `list_source_files` -- the shape of the repository at this revision.
* `search_source` -- a regular expression for the prompt text, tool name, or
  error string the insight points at.
* `read_source_file` -- the surrounding lines, numbered, so quotes can be cited
  exactly.

### 3. Pull the evidence

Call `get_full_trajectories` with `occurrence_id=<occurrence_id>` when the
question turns on what users actually did. That is the sighting you took the
revision from, so its conversations are the ones the code you just read
served. The response is scoped to that sighting: `scope` is `"occurrence"` and
`agent_revision` at the top level is the revision you already have.

The sample carried on the insight itself is capped rubric evidence, not the
whole population, so read the conversations rather than reasoning from it.

If one sighting is not enough evidence, call again with `insight_id` alone and
no `occurrence_id`. That returns the recent sightings of the insight, newest
first, with `scope` set to `"insight"`. The top-level `agent_revision` is then
`null`, because the conversations span builds: each trajectory entry carries its own
`occurrence_id` and `agent_revision`, and that per-entry revision is the one to
pass when reading source for that conversation.

Paginate with `next_page_token`. A trajectory marked `partial`, `truncated`, or
`not_archived` is incomplete evidence -- say so rather than reasoning over the
gap.

This response is capped: `occurrences_read`, `total_occurrences`, and
`occurrences_truncated` describe how much of the insight it covers. Never state
how often the issue happened from these numbers -- `get_insight` is what counts
occurrences.

### 4. Record the fix, then answer

Call `record_root_cause`, then write the reply. The written answer has exactly
two parts, in this order, naming both the revision you read and the occurrence
you took it from. The fix is not one of them.

## Recording the fix

The fix is the tool call, not prose. Pass the `insight_id`, the `occurrence_id`
you took the revision from, that same `revision`, a `summary` naming the
mechanism, and `edits` -- one per replacement, each a `path`, a 1-based
inclusive `start_line`..`end_line`, the replacement text in `after`, and a
one-line `rationale`. Leave `before` empty: the server fills it from the snapshot and
discards anything you send, so read the `record` it returns to confirm the
anchor is the code you meant.

Call it once you can explain the mechanism. Call it again with the **complete**
edit set whenever the diagnosis changes -- each call supersedes the last for that
occurrence, and the newest is what the dashboard shows. There is no way to add
or remove one edit, so resend every edit you still stand behind. If an edit is
gone because the user asked for a narrower fix, there is nothing to report; if
one disappeared and you did not intend it, put it back.

An empty `edits` set is a legitimate answer when the diagnosis needs no code
change. Say so in the summary.

The tool refuses the whole record if any one edit cannot be anchored, and names
the failing range and why. Correct that range and resend; `anchored` gives back
the edits that did resolve. If every edit is refused, state the fix in prose and
tell the user the record was not saved.

## The answer contract

**1. The mechanism.** What in the code produces the observed behavior, cited as
`<path>:<start>-<end>` and quoting the code as it exists at the revision you
read. State that revision explicitly in the answer.

**2. That the fix is unverified.** Say it, every time, in a sentence of its
own: nothing here ran the fix or tested it. Most of these defects are prompt or
instruction wording, where a passing test suite would not show that the behavior
changed either. Omitting the sentence reads as confidence you do not have.

If the revision you read is not the newest snapshot, say so here too: the file
may have moved on since.

## Never write the fix out

The dashboard renders the stored record directly above your reply, so repeating
it shows the user the same edit twice. Write no "proposed fix" section, no path,
no line range, no `before` or `after` block, no replacement text, and never a
unified diff -- a `--- a/... +++ b/...` block invites `git apply`, and the
snapshot is a past revision while the working tree is at HEAD, so such a patch
can apply cleanly and land the wrong change.

Point at the record in one sentence -- which files it touches, and that the
record carries the edit -- and stop there. The one exception is a record the
tool refused outright: nothing is on screen then, so state the fix in prose and
say it was not saved.

## Code and conversations must be the same revision

The revision you read the source at and the revision the conversations you quote
ran on have to be the same one, and the answer has to say which it is. Nothing
enforces this for you: the revision is an argument you pass, so reading revision
10 while quoting a sighting from revision 8 produces an explanation of code that
never served those conversations. Name the revision and the occurrence together,
and if you had to mix them, say that instead of presenting one revision.

Under `"insight"` scope the revision varies from one trajectory entry to the
next, so there is no single revision the answer can name. Either explain each
build against the entries that ran on it, or restrict the explanation to one
revision and say which conversations it covers.

## Absent code

A file the snapshot does not have is one of three different answers, and the
tools distinguish them. Report the one you got:

* excluded by a publish-time ignore pattern -- the code exists, this snapshot
  does not carry it;
* no such path at this revision -- it does not exist in the repository;
* published but with its body missing, which means the deploy-time upload did
  not finish -- another revision may carry the same file.

`record_root_cause` reports whichever of the three applies to an edit's path.
A third-party dependency is a fourth case that no snapshot covers at all: their
behavior has to be reasoned about from the call sites you can read.

Never present "not in this snapshot" as "does not exist".