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

# Validate a change with your AI assistant

> Have your assistant choose the checks a change needs, run them on the right revision, and report what passed, failed, was cached or could not run.

Ask your assistant to validate a change and it should answer one question
truthfully: what did each check prove about *this* revision? This page is the
workflow it follows. Give it the page along with
[Use ReasonOS with your AI assistant](https://docs.reasonos.com/ai.md).

## Start with a request like this

> Validate the change on my branch before I ask for review. Find the targets it
> affects, run their tests with coverage on the exact commit, and tell me what
> passed, what failed, what was replayed from cache and what could not run.
> Ask before starting anything that uses a QA agent or a model.

## Choose where the checks run

Two connections can run checks. Use whichever your assistant has; they are not
interchangeable.

**Local RBS MCP** (`rbs mcp serve`) checks your local workspace, with files
as they are now:

* `rbs_affected` — the targets and tests a set of changed files affects
* `rbs_build`, `rbs_test`, `rbs_coverage` — build, test and coverage; each
  answers when it finishes

**Managed ReasonOS MCP** checks a clean checkout of an exact commit on the
branch's running server:

* `start_branch_execution` — build, test or coverage (`mode`) of exact targets
* `branch_execution_status` — follow it (`wait_seconds` to wait); it shows only
  the log's tail
* `get_branch_execution_log` — a finished run's whole log, one page at a time,
  for the person who started it
* `start_ci_run`, `ci_status`, `get_ci_run`, `get_ci_run_log` — CI
* `issue_evidence` — the evidence linked to an issue

[Know which connection you have](https://docs.reasonos.com/ai.md#know-which-connection-you-have) explains
what each one can reach. A managed run needs the branch server already open; it
never starts one, and it never uses or touches unsaved work in the shared
workspace.

## The workflow

1. **Pin what is being checked.**
   * Managed: name the branch and the full commit hash. The run checks exactly
     that commit.
   * Local: the tools check the working files, not a commit. Record `HEAD` and
     whether the working tree is clean before and after the run. Call a result
     evidence for that commit only if the tree was clean and unchanged
     throughout; otherwise call it evidence for the workspace with its
     uncommitted changes. Never stash, revert, stage or commit someone's work
     just to get a clean tree.
2. **Choose bounded checks.** Locally, give `rbs_affected` the files the change
   touched: it returns what to rebuild and which tests to run, and lists any file
   no target owns separately, so you know the graph did not cover it. Run those
   tests, not the whole workspace.
3. **Run them.**
   * Locally: `rbs_test` or `rbs_coverage` with those targets. Coverage uses the
     same floors as `rbs coverage`; an unmet floor fails the check. `rbs_test`
     takes a `filter` to re-run one case; a filtered run is never cached.
     Both tools take `runner_args`, a list of arguments for the test runner
     (for Go, `["-count=2", "-v"]`). A run with runner arguments requires
     exactly one test in its resolved dependency closure and is never cached.
     Runner arguments can start other programs, so the local server offers
     them only when started with `--allow-write` or `--tools full`; get the
     person's authorization to run commands if it is not already in scope.
   * Managed: `start_branch_execution` with the full commit hash, the targets
     and a `request_key` you make up, such as `issue-12-test-1`. Then follow it
     with `branch_execution_status`.
4. **Read the outcome per check**, then report each one as exactly one of:
   * **Passed** — the test process ran on this revision and succeeded.
   * **Replayed from cache** — reported as `cached pass from <time>; test process
     not run`. It is a pass recorded for identical inputs, not a new run; say so.
   * **Failed** — include the failing test's log, or for coverage the unmet floor.
   * **Skipped** — a CI job or test that did not run by design, such as a job
     the change did not affect. It is not a pass.
   * **Not run** — the server was not open, a service was unavailable, the
     target did not build, or you were not allowed to run it. Say which.
   * **Unknown** — the run's outcome could not be confirmed (see below).
5. **Link the evidence.** On a managed project, `issue_evidence` shows each CI
   run and execution judged against the issue's linked change: current (at its
   head) or stale (at an older commit).

## Approval points

Builds, tests and coverage on the person's own branch use their existing
permissions. Ask first before:

* starting a [QA](https://docs.reasonos.com/platform/qa.md) run, which uses QA workers and a model;
* re-running CI for someone else's change;
* anything that merges, deploys or changes settings — validation never does.

## When things go wrong

* **A new commit lands.** Every earlier result is now stale for the change.
  Re-run the affected checks on the new commit, or report them as stale; a pass
  on an older commit does not verify a later one.
* **The answer to a start is lost** (a timeout or dropped connection). Ask
  `branch_execution_status`, or resend the *same* request with the *same*
  `request_key`: the first attempt is answered and nothing new runs. Never
  retry with a new key; that can run the work twice.
* **You cancel a run.** One that had not started is cancelled. One already
  running is asked to stop and often ends `unknown`, because a stopped command
  cannot confirm what it did. Report it as unknown, not passed or failed.
* **A log is long.** `branch_execution_status` shows only the tail. Before
  saying you read a whole execution log, follow `get_branch_execution_log`'s
  `next_from` until there is none. `get_ci_run_log` starts at the last page,
  where failures usually are; `source_truncated` means the stored log lost its
  beginning.

## Limits today

* This page describes the current tools. A hosted deployment may run an
  earlier build: use the tools your connection actually offers, and report a
  missing one rather than working around it.

* Runner arguments need a local server started with `--allow-write` or
  `--tools full`, and a build of rbs that includes them. A default connection
  does not show `runner_args` at all. The command-line equivalent,
  `rbs coverage //t -- -count=2`, needs the same authorization to run commands.

* Affected-target discovery is a local tool; the managed connection has no
  equivalent yet.

* A green check is evidence about source, not about what is deployed: a
  passing run, a merge or a tag does not show which version is running.


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