Issues vs persona feedback

A run reports four kinds of record. Only one of them is a defect, and only part of that one may become a ticket by itself:

Record	What it is	Route	A ticket?
Issue	A product defect, which a replay without the persona then tried to reproduce	get_issues	Only when may_file_ticket_alone is true
Verdict	Each persona’s answer at the end of its session, quoted from its diary	get_verdicts	Never
Opportunity	What the personas’ behaviour says the product could do better, or already does well	get_opportunities	Never
Tester error	A slip the persona made, such as a mistyped password	get_tester_errors	Never

All four routes answer from the moment the run exists. While it is still going they answer an empty list beside the run’s status, so an empty list is a result only once status is terminal. get_artifact answers everything in one document. Over MCP, the tools of the same names answer the same records (MCP tools).

Issues: defects, checked by a replay

An issue is something the product did wrong: where, in how many of the sessions that got there, with its evidence and the steps that reproduce it. Its type is blocker, friction, confusion, bug or contradiction, and its severity is low, medium, high or critical.

After the sessions, Saram tries to reproduce each issue: a replay walks the recorded path again with no persona and no model, twice, with your app reset before each attempt. The result is in reproduction (reproduced, not_reproduced, flaky or skipped), and what it proved is in claim.verification.status:

verification.status	Meaning	Files alone?
verified	The replay failed at the same step, a second check found the issue’s title supported by a verbatim quote from the recorded steps, and the failure is the product’s, not the persona’s	Yes
marker_matched	The replay failed at the same step, but whether it failed for the reason the title gives is not established	No
inconclusive	A check ran and settled nothing: the failure did not come back, or the two attempts disagreed. Not a refutation	No
unverified	Nothing checked it. Also how to read an issue with no verification at all	No

reproducible is true exactly when the status is verified. To check an issue again later, after a fix, retest_issue runs the same replay now and keeps the answer beside the run’s own; a replay’s steps are never billed.

The reading beside each issue

GET /api/v1/runs/{run_id}/issues answers issues[] and, beside it, one reading[] entry per issue:

{
  "issue_id": "iss_signup_submit_500",
  "may_file_ticket_alone": true,
  "subjective_fields": ["persona_rationale"],
  "advisory": "SUBJECTIVE. `persona_rationale` is persona-voiced narration from an affected session, not a statement of observed behaviour. Quote it as the persona's words; the objective claim is `description`."
}

• may_file_ticket_alone: true means reproduction cleared the issue as a confirmed bug. File it as it stands.
• false means report it with its evidence and mark it unconfirmed. It may be real; nothing has proved it yet.
• subjective_fields names the fields in the persona’s voice. An issue’s description is the objective account; persona_rationale is what the persona felt. Quote the second as the persona’s words, and do not merge it into the first.

get_issue answers one issue in full: its claim and how it was checked, the repro steps, the preconditions and the evidence refs.

Verdicts and opportunities: persona feedback

Both are opinions. They are grounded in what the personas did and said, and they are still opinions: say whose they are, and never state them as fact.

• Verdicts are each persona’s answer to the run’s verdict question (mission.verdict_prompt, or the persona’s own), quoted from its diary, with the cohort’s tally of positive, negative and undecided. A verdict the judge gave but could not ground in the persona’s diary is thrown away and counts as undecided; the row says so in verdict_discarded.
• Opportunities are unmet expectations, missing capabilities, value and trust gaps, and moments of delight. They are scored by consensus, the share of the sessions that reached the area and raised it, never by reproduction. display.shown lists the ones that clear the cohort floors, and display.folded the single-persona notes. A moment that worked well is an opportunity of kind delight, never an issue.

Each answer carries an advisory saying how to read it.

Tester errors: the harness’s own slips

Some failures are the persona’s, not the product’s: it typed a password that differs from the one its account gave it, clicked the wrong element, or read placeholder text as a value. Saram asks of every finding whether the persona’s own action could explain it, and records the answer as claim.attribution:

• product: the failure is the product’s.
• tester: the record moves to tester_errors[]. It is not an issue, is not counted in issues_total, is not reproduced and is never a ticket.
• undetermined: the harness could not tell, and a person must. Such an issue is never verified.

Read tester errors for why a session stalled and what to fix in your test setup, such as a stale password in a test account. classified: false means the run’s artifact is from before this sorting existed, not that it found none.

The confirmation rate

A run’s confirmation_rate (get_run) is the confirmed issues over the issues reproduction ruled on. It is there as soon as reproduction finishes. Read it with its denominator, summary.reproduction:

{
  "candidates": 2,
  "merged": 1,
  "evaluated": 1,
  "confirmed": 1,
  "inconclusive": 0,
  "excluded": 0
}

candidates are the per-session findings the judge raised, merged what they became once the same defect seen in several sessions was folded into one, evaluated the ones reproduction ruled on, and confirmed the ones it confirmed. A rate over an evaluated of 0 says nothing: a run that found nothing reads 0.0. Do not compare runs by the rate alone.

What to file as a ticket

1. File an issue whose reading says may_file_ticket_alone: true, with its repro steps, evidence and objective description.
2. Report an issue whose reading says false as unconfirmed, with its evidence, never as a confirmed bug. A person can look at the evidence, or retest_issue can try it again.
3. Never file a verdict or an opportunity as a ticket. Take them to whoever owns the product decision, attributed to the persona.
4. Never file a tester error against the product. Fix the test setup it points at.

With connectors.github on a Pro plan, Saram files issues on GitHub itself (The run spec).

What was checked

Block	Checked
The four routes, their advisory and reading	2026-10-23, on a finished run against api.saram.sh (platform-api 0.9.0)
The reading and the reproduction counts shown	The examples in the reference’s get_issues and get_run (/openapi.json)
The verification statuses and attributions	The Status and Attribution schemas in the reference