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

# Report, reproduce and verify findings

> Keep observed failures, deterministic replay and advisory exploration distinct.

A useful finding explains what happened, what should have happened, who is affected and how someone else can observe the problem. Evidence supports the observation; analysis explains your best current interpretation without claiming an unverified root cause.

## Capture a finding worth investigating

For the saved-view example, record the exact filters, actions and observed reset. Use synthetic or redacted values. Include an absolute application URL, severity, reproduction steps, best-effort analysis and analysis confidence. Separate reproduction confidence from root-cause confidence.

Search existing findings first. Inspect screenshots for static issues; inspect the video and its observed sequence for timing, transitions or other temporal issues. Attach relevant console/network logs or traces when they help explain the failure. Never attach auth state, secrets or unrelated private pages.

The [HTTP guide](https://docs.bugspray.io/reference/http-api.md) supports metadata-only storage. Agent `submit_finding` follows a stricter verified-reporting guide: final-state verification, duplicate-search attestation, inspected visual evidence, explicit auth intent and a deterministic repro or concrete omission reason. Fetch that guide before reporting.

## Review evidence and ownership

Use Findings to search, sort and filter status or included/excluded tags. Open a finding to inspect evidence, discuss it in comments and assign remediation ownership. Browser videos support reviewing the observed sequence; validated repro markers connect steps to recording timestamps. Uploaded originals are retained; local ffmpeg can add MP4 for WebM, while hosted ingestion serves original R2 media without transcoding. Retention is deployment-specific.

Issue links and notifications are optional. A Slack delivery failure is logged without rejecting an ordinary stored finding. Validation-gated agent submissions have their own acceptance workflow.

## Enable execution deliberately

Keep `BUGSPRAY_ENABLE_REPRO_EXECUTION=0` for evaluation. To run reviewed scripts, use a dedicated environment, install Chromium and required recording tools, and explicitly set `BUGSPRAY_ENABLE_REPRO_EXECUTION=1` before startup.

Local repros spawn processes on the host. Hosted repros use Containers. Neither is a hostile-code sandbox. Use low-privilege test accounts and keep production secrets and unrelated volumes out of the runner. Read the repository [trust model](https://github.com/SynclyUS/bugspray/blob/main/docs/trust-model.md).

A script attachment alone does not execute it. The MCP validated-submission path requires execution-enabled validation and fails explicitly when that capability is disabled.

## Read replay outcomes

| Outcome | Interpretation |
| - | - |
| `reproduced` | The script observed the reported problem |
| `not_reproduced` | The script did not observe it under the tested conditions |
| `inconclusive` | The evidence did not decide the question |
| `failed_to_run` | Execution could not produce a valid observation |

A **canonical run** is the finding's own latest run against its filed deployment. Only canonical outcomes move remediation status. A latest `not_reproduced` marks it fixed; `reproduced` normally opens it or preserves active ownership. A fix verified against a linked PR is provisional: another reproduced result keeps it fixed until merge is confirmed; reproduction after merge identifies a regression and returns it to `in_progress`.

A **hypothetical replay** tests the same script against a candidate build. PR regression replay is hypothetical: it does not become the finding's latest canonical run and does not change remediation status.

## Keep exploration separate

An advisory AI browser sweep looks for additional problems and produces observations. It is not a deterministic suite result. A green replay, empty replay set or advisory check does not establish that registered test suites passed. Read the suite section of a [PR report](https://docs.bugspray.io/guides/pr-validation.md) independently.

For script environment variables, result JSON and sequential `test.step("Repro 1", ...)` markers, use the maintained [repro contract](https://github.com/SynclyUS/bugspray/blob/main/docs/api.md#repro-script-contract). Scripts contain product actions; managed auth profiles supply login state.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.